<html>
<head><title>IC Programmers Manual</title></head>
<!-- 01-08-05 version -->
<body>
<br><center>
<font size=+4><b>IC Programmers Manual for the Sumo11 Controller</b></font><br>
</center>

<a name="PM Index"></a><center>
<font size=+3><b>Programmers Manual Index</b></font><br>
</center>
<ol>
<li><a href="#Introduction">Introduction</a><br>
<li><a href="#Using IC">Using IC</a><br>
<li><a href="#IC Interface">IC Interface</a><br>
<li><a href="#The  main() Function">The  main() Function</a><br>
<li><a href="#IC versus Standard C">IC versus Standard C</a><br><ul type=disc>
    <li><a href="#A Quick C Tutorial">A Quick C Tutorial</a><br><ul>
        <li><a href="#return type">return type</a><br>
        <li><a href="#return statement">return statement</a><br></ul></ul>
<li><a href="#Data Objects">Data Objects</a><br><ul type=disc>
    <li><a href="#Variables">Variables</a><br><ul>
        <li><a href="#Declaration">Declaration</a><br>
        <li><a href="#Local and Global Scopes">Local and Global Scopes</a><br>
        <li><a href="#Variable Initialization">Variable Initialization</a><br>
        <li><a href="#Local and Global Scopes">Persistent Global Variables</a><br></ul>
    <li><a href="#Constants">Constants</a><br><ul>
        <li><a href="#Integer Constants">Integer Constants</a><br>
        <li><a href="#Long Integer Constants">Long Integer Constants</a><br>
        <li><a href="#Floating Point Constants">Floating Point Constants</a><br>
        <li><a href="#Characters and String Constants">Characters and String Constants</a><br>
        <li><a href="#Integer Constants">Integer Constants</a><br>
        <li><a href="#NULL">NULL</a><br></ul>
    <li><a href="#Data Types">Data Types</a><br><ul>
        <li><a href="#16-bit Integers">16-bit Integers</a><br>
        <li><a href="#32-bit Integers">32-bit Integers</a><br>
        <li><a href="#32-bit Floating Point Numbers">32-bit Floating Point Numbers</a><br>
        <li><a href="#8-bit Characters">8-bit Characters</a><br>
        <li><a href="#Pointers">Pointers</a><br>
        <li><a href="#Arrays">Arrays</a><br>
        <li><a href="#Structures">Structures</a><br></ul>
    <li><a href="#Data Types">Pointers</a><br><ul>
        <li><a href="#Pointer Safety">Pointer Safety</a><br>
        <li><a href="#Pointer Declaration and Use">Pointer Declaration and Use</a><br>
        <li><a href="#Passing Pointers as Arguments">Passing Pointers as Arguments</a><br>
        <li><a href="#Returning Pointers from Functions">Returning Pointers from Functions</a><br></ul>
    <li><a href="#Arrays">Arrays</a><br><ul>
        <li><a href="#Declaring and Initializing Arrays">Declaring and Initializing Arrays</a><br>
        <li><a href="#Passing Arrays as Arguments">Passing Arrays as Arguments</a><br>
        <li><a href="#Multi-dimensional Arrays">Multi-dimensional Arrays</a><br>
        <li><a href="#Determining the size of Arrays at Runtime">Determining the size of Arrays at Runtime</a><br>
        <li><a href="#Uploading Arrays">Uploading Arrays</a><br></ul>
    <li><a href="#Structures2">Structures</a><br>
    <li><a href="#Complex Initialization examples">Complex Initialization examples</a><br></ul>
<li><a href="#Statements and Expressions">Statements and Expressions</a><br><ul type=disc>
    <li><a href="#Operators">Operators</a><br><ul>
        <li><a href="#Integer Operations">Integer Operations</a><br>
        <li><a href="#Long Integers">Long Integers</a><br>
        <li><a href="#Floating Point Numbers">Floating Point Numbers</a><br>
        <li><a href="#Characters">Characters</a><br></ul></ul>
<li><a href="#Assignment Operators and Expressions">Assignment Operators and Expressions</a><br>
<li><a href="#Increment and Decrement Operators">Increment and Decrement Operators</a><br>
<li><a href="#Data Access Operators">Data Access Operators</a><br>
<li><a href="#Precedence and Order of Evaluation">Precedence and Order of Evaluation</a><br>
<li><a href="#Control Flow">Control Flow</a><br>
    <li><a href="#Statements and Blocks">Statements and Blocks</a><br><ul type=disc>
    <li><a href="#If-Else">If-Else</a><br>
    <li><a href="#While">While</a><br>
    <li><a href="#For">For</a><br>
    <li><a href="#Break">Break</a><br></ul>
<li><a href="#LCD Screen Printing">LCD Screen Printing</a><br><ul type=disc>
    <li><a href="#Printing Examples">Printing Examples</a><br><ul>
        <li><a href="#Printing a message">Printing a message</a><br>
        <li><a href="#Printing a number">Printing a number</a><br>
        <li><a href="#Printing a number in binary">Printing a number in binary</a><br>
        <li><a href="#Printing a floating point number">Printing a floating point number</a><br>
        <li><a href="#Printing two numbers in hexadecimal format">Printing two numbers in hexadecimal format</a><br></ul>
    <li><a href="#Formatting Command Summary">Formatting Command Summary</a><br></ul>
<li><a href="#Preprocessor">Preprocessor</a><br><ul type=disc>
    <li><a href="#Preprocessor Macros">Preprocessor Macros</a><br>
    <li><a href="#Conditional compilation">Conditional compilation</a><br>
    <li><a href="#Comparison with regular C preprocessors">Comparison with regular C preprocessors</a><br></ul>
<li><a href="#The IC Library File">The IC Library File</a><br><ul type=disc>
    <li><a href="#Commonly Used IC Library Functions">Commonly Used IC Library Functions</a><br><ul>
        <li><a href="#digitalx"><font color=darkblue>digital</font></a><br>
        <li><a href="#analogx"><font color=darkblue>analog</font></a><br>
        <li><a href="#sleepx"><font color=darkblue>sleep</font></a><br>
        <li><a href="#beepx"><font color=darkblue>beep</font></a><br>
        <li><a href="#tonex"><font color=darkblue>tone</font></a><br>
        <li><a href="#printfx"><font color=darkblue>printf</font></a><br>
        <li><a href="#motorx"><font color=darkblue>motor</font></a><br>
        <li><a href="#fdx"><font color=darkblue>fd</font></a><br>
        <li><a href="#bkx"><font color=darkblue>bk</font></a><br>
        <li><a href="#offx"><font color=darkblue>off</font></a><br>
        <li><a href="#aox"><font color=darkblue>ao</font></a><br></ul>
    <li><a href="#Processes">Processes</a><br><ul>
        <li><a href="#start_processx"><font color=darkblue>start_process</font></a><br>
        <li><a href="#deferx"><font color=darkblue>defer</font></a><br>
        <li><a href="#kill_processx"><font color=darkblue>kill_process</font></a><br></ul>
    <li><a href="#Encoders">Encoders</a><br><ul>
        <li><a href="#xenable_encoder"><font color=darkblue>enable_encoder</font></a><br>
        <li><a href="#xdisable_encoder"><font color=darkblue>disable_encoder</font></a><br>
        <li><a href="#xreset_encoder"><font color=darkblue>reset_encoder</font></a><br>
        <li><a href="#xread_encoder"><font color=darkblue>read_encoder</font></a><br></ul>
    </ul>
<li><A href="#Functions">Sumo11 Specific Functions</A></LI>
<li><a href="#Simulator">Simulator Instructions</A></li>
</ol>

<a name="Introduction"></A>

<font size=+3><b>Introduction</b></font>
<p>
Interactive C (IC for short) is a C language consisting of a compiler (with interactive command-line
compilation and debugging) and a run-time machine language module. IC implements a subset of C including
control structures (<a href="#For"><font color=blue>for</font></a>, <a href="#While"><font color=blue>while</font></a>,
<a href="#If-Else"><font color=blue>if</font></a>, <a href="#If-Else"><font color=blue>else</font></a>), local and global variables, arrays, pointers, structures,
16-bit and 32-bit integers, and 32-bit floating point numbers.
<p>
IC works by compiling into pseudo-code for a custom stack machine, rather than compiling directly into
native code for a particular processor. This pseudo-code (or <i>p-code</i>) is then interpreted by the run-time
machine language program. This unusual approach to compiler design allows IC to offer the following design
tradeoffs:
<ul><li><b>Interpreted execution</b> that allows run-time error checking. For example, IC does
array bounds checking at run-time to protect against some programming errors.
<li><b>Ease of design</b>. Writing a compiler for a stack machine is significantly easier than
writing one for a typical processor. Since IC's p-code is machine-independent,
porting IC to another processor entails rewriting the p-code interpreter, rather than
changing the compiler.
<li><b>Small object code</b>. Stack machine code tends to be smaller than a native code
representation.
<li><b>Multi-tasking</b>. Because the pseudo-code is fully stack-based, a process's state is
defined solely by its stack and its program counter. It is thus easy to task-switch
simply by loading a new stack pointer and program counter. This task-switching
is handled by the run-time module, not by the compiler.
</ul>
Since IC's ultimate performance is limited by the fact that its output p-code is interpreted,
these advantages are taken at the expense of raw execution speed.

<table><tr><td><font face="Times"><dl><dd><i>IC 5 was written by Kyle Machulis/KISS Institute 
for Practical Robotics. Portions of the code and the libraries are
based on the public distribution of IC 4.x by Randy Sargent with assistance from Mark Sherman, and IC 2.8,
written by Randy Sargent, Anne Wright and Fred Martin.
</i></font></td></tr></table>
<br>
<!---->
<a name="Using IC"></a>
<font size=+3><b>Using IC</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
When IC is running and has a connection to a compatible processor board such as the
Handy Board or RCX, C expressions, function calls, and IC commands may be typed in
the command entry portion of the interaction window.
<p>
For example, to evaluate the arithmetic expression 1 + 2, type in the following:
<table><tr><td><pre>   1 + 2;</td></tr></table>
When this expression is entered from the interaction window, it is compiled by the
console computer and then downloaded to the attached system for evaluation. The
connected board then evaluates the compiled form and returns the result, which is printed
on the display section of console interaction window.
<p>
To evaluate a series of expressions, create a C block by beginning with an open curly
brace { and ending with a close curly brace }. The following example creates a local
variable <font face="Courier">i</font> and prints 10 (the sum of <font face="Courier">i + 7</font>) to the board's LCD screen:
<table><tr><td><pre>   {<font color=blue>int</font> i=3; <font color=purple>printf</font>(<font color=red>"%d"</font>, i+7);}</td></tr></table>
<br>
<!---->
<a name="IC Interface"></a>
<font size=+2><b>IC Interface</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
Both new (unsaved) and saved files can be opened for editing in IC.  A row of tabs lists
the files that have been opened.  Clicking a file's tab activates it for editing.  The first tab
for the interface is always the interaction window.
<p>
The <font face="Ariel"><b><u>F</u>ile</b></font> button has standard entries for
<font face="Ariel"><b><u>N</u>ew</b></font>, <font face="Ariel"><b><u>O</u>pen</b></font>, <font face="Ariel"><b><u>C</u>lose</b></font>,
<font face="Ariel"><b><u>S</u>ave</b></font>, <font face="Ariel"><b>Save <u>A</u>s</b></font>, <font face="Ariel"><b><u>P</u>rint</b></font>, and
<font face="Ariel"><b>E<u>x</u>it</b></font>.  Under <font face="Ariel"><b><u>F</u>ile - Save <u>A</u>s</b></font>,
if no file name extension is supplied, IC automatically saves
with the "<b><font face="Courier">.ic</font></b>" extension.
<p>
To download the active file, simply click the download button.  The active file will also
be saved, unless it is new, in which case the user is prompted for a "save as" file name.
Remark: a <a href="#Preprocessor">preprocessor</a> command  <font color=blue face="Courier">#use</font> has been added to IC to specify any other saved
files (personal libraries) that need to be downloaded along with the active file [Note:
<font color=blue face="Courier">#use</font> is quite different from the
<font face="Courier">#include</font> prepreocessor command of standard C
environments.  <font face="Courier">#include</font> is not implemented for reasons given later in the section
describing the IC-preprocessor.]
<p>
If a downloaded program does not do what is intended, it may corrupt the p-code
interpreter, particularly if pointers are being employed.   The interface provides an option
under the <font face="Ariel"><b><u>S</u>ettings</b></font> button for downloading the firmware to reinitialize the board.
<p>
When there is a connection to a board and the downloaded programs include "main", then
"main" can be executed using the <font face="Ariel"><b>Run Main</b></font> button.
The <font face="Ariel"><b>Stop</b></font> button will halt execution of the attached system.
<p>
Under the <font face="Ariel"><b><u>T</u>ools</b></font> button, among other options, are ones for listing downloaded files,
global variables, and functions (including library functions).
<p>
The interface provides additional capabilities for program entry/edit, minor adjustment to
the display, and for setting up the serial interface to a board.  In particular, the <b>Check</b> tool will perform
a syntax check of the C program currently in the window.  If there is an error, the approximate line
number where the error is located is reported (the error is on the line or a nearby prior line).  The edit
button provides a <font face="Ariel"><b><u>G</u>o to line</b></font> option.
<p>
C programs are automatically formatted and indented.  Keywords, library functions,
comments, and text strings are high-lighted with color unless this feature is turned off.
<p>
IC does parenthesis-balance-highlighting when the cursor is placed to the right of any
right parenthesis, bracket, or brace.
<p>
<!---->
<a name="The  main() Function"></a>
<font size=+2><b>The  <font face="Courier" color=blue>main()</font> Function</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
After functions have been downloaded to a board, they can be invoked from IC so long as
the board is connected.  If one of the functions is named <font face="Courier">main()</font>, it can be run directly
from the interface as noted earlier, and otherwise will be run automatically when the
board is reset.
<p>
Note: to reset the Handy Board without running the <font face="Courier">main()</font> function (for instance, when
hooking the board back to the computer), hold down the boarentry.d's <b>Start</b> button while
activating the board.  The board will then reset without running <font face="Courier">main()</font>.
<p>
<!---->
<a name="IC versus Standard C"></a>
<font size=+3><b>IC versus Standard C</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
The IC programming language is based loosely on ANSI C. However, there are major
differences.
<p>
Many of these differences arise from the desire to have IC be "safer" than standard C. For
instance, in IC, array bounds are checked at run time; for this reason, arrays cannot be
converted to pointers in IC. Also, in IC, pointer arithmetic is not allowed.
<p>
Other differences are due to the desire that the IC runtime be small and efficient. For
instance, the IC <a href="#printf"><font face="Courier" color=purple>printf</font></a> function does not understand many of the more exotic
formatting options specified by ANSI C.
<p>
Yet other differences are due to the desire that IC be simpler than standard C. This is the
reason for the global scope of all declarations.
<p>
In the rest of this document, when we refer to "C", the statement applies to both IC and
standard C. When we wish to specify one or the other, we will refer to either "IC" or
"standard C". When no such qualifiers are present, you should assume that we are talking
about IC.
<p>
<!---->
<a name="A Quick C Tutorial"></a>
<font size=+3><b>A Quick C Tutorial</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
Most C programs consist of function definitions and data structures. Here is a simple C
program that defines a single function, called <b>main</b>.
<pre><font color=darkgreen>/* <i>Simple example
     IC Programmer's Manual</i>
     */</font>
  <font color=blue>void</font> main()
  {
      <font color=blue>printf</font>(<font color=red>"Hello, world!\n"</font>); <font color=darkgreen>// <i>Something simple</i></font>
  }
</pre>
The expression
<table><tr><td><dl><dd><font face="Courier">/* &lt;</font><i>text</i><font face="Courier">&gt; */</font></td></tr></table>
forms a <i>multi-line</i> or <i>bracketed comment</i>.  In contrast, text that starts with
"<font face="Courier">//</font>" forms a <i>single line comment</i>, which continues only to the end of the line.
Comments are ignored by IC when the program is compiled.
<p><a name="return type"></a>
All functions must have a return type. Since <b>main</b> does not return a value, it uses
<font face="Courier" color=blue>void</font>,
the null type, as its return type. Other types include integers (<font face="Courier" color=blue>int</font>) and floating point
numbers (<font face="Courier" color=blue>float</font>). This <i>function declaration</i> information must precede each function
definition.
<p>
Immediately following the function declaration is the function's name (in this case,
<b>main</b>). Next, in parentheses, are any arguments (or inputs) to the function.
<b>main</b> has
none, but an empty set of parentheses is still required.
<p>
After the function arguments is an open curly-brace {. This signifies the start of the
actual function code. Curly-braces signify program <i>blocks</i>, or chunks of code.
<p>
Next comes a series of <i>C statements</i>. Statements demand that some action be taken. Our
demonstration program has a single statement, a <font face="Courier" color=purple>printf</font> (formatted print). This will
print the message <b>"Hello, world!"</b> to the LCD display. The <b>\n</b> indicates end-of-line.
The <font face="Courier" color=purple>printf</font> statement ends with a semicolon (;). <i>All</i> C statements must be ended by a
semicolon. Beginning C programmers commonly make the error of omitting the
semicolon that is required to end each statement.
<p>
The <b>main</b> function is ended by the close curly-brace }.
<p>
Let's look at an another example to learn some more features of C. The following code
defines the function <i>square</i>, which returns the mathematical square of a number.
<pre><font color=blue>int</font> square(<font color=blue>int</font> n)
   {
       <font color=blue>return</font>(n * n);
   }
</pre>
The function is declared as type <font face="Courier" color=blue>int</font>, which means that it will return an integer value.
<p>
Next comes the function named <b>square</b>, followed by its argument list in parentheses.
square has one argument, <b>n</b>, which is an integer. Notice how declaring the type of the
argument is done similarly to declaring the type of the function.
<p>
When a function has arguments declared, those argument variables are valid within the
"scope" of the function (i.e., they only have meaning within the function's own code).
Other functions may use the same variable names independently.
<p><a name="return statement"></a>
The code for <b>square</b> is contained within the set of curly braces. In fact, it consists of a
single statement: the <font face="Courier" color=blue>return</font> statement. The
<font face="Courier" color=blue>return</font> statement exits the function and
returns the value of the C <i>expression</i> that follows it (in this case "<b>n * n</b>").
<p>
Except where grouped by parentheses, expressions are evaluated according to a set of
precedence rules associated with the various operations within the expression. In this
case, there is only one operation (multiplication), signified by the "<b>*</b>", so precedence is
not an issue.
<p>
Let's look at an example of a function that performs a function call to the square program.
<pre><font color=blue>float</font> hypotenuse(<font color=blue>int</font> a, <font color=blue>int</font> b)
   {
       <font color=blue>float</font> h;
       h = <font color=purple>sqrt</font>((<font color=blue>float</font>)(square(a) + square(b)));
       <font color=blue>return</font>(h);
   }
</pre>
This code demonstrates several more features of C. First, notice that the floating point
variable <b>h</b> is defined at the beginning of the <b>hypotenuse</b> function. In general, whenever
a new program block (indicated by a set of curly braces) is begun, new local variables
may be defined.
<p>
The value of <b>h</b> is set to the result of a call to the <font face="Courier" color=purple>sqrt</font> function. It turns out that
<font face="Courier" color=purple>sqrt</font> is a
built-in IC function that takes a floating point number as its argument.
<p>
We want to use the <b>square</b> function we defined earlier, which returns its result as an
integer. But the sqrt function requires a floating point argument. We get around this
type incompatibility by coercing the integer sum <b>(square(a) + square(b))</b> into a
float by preceding it with the desired type, in parentheses. Thus, the integer sum is
made into a floating point number and passed along to <font face="Courier" color=purple>sqrt</font>.
<p>
The <b>hypotenuse</b> function finishes by returning the value of <b>h</b>.
<p>
This concludes the brief C tutorial.
<p>
<!---->
<a name="Data Objects"></a>
<font size=+3><b>Data Objects</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
Variables and constants are the basic data objects in a C program. Declarations list the
variables to be used, state what type they are, and may set their initial value.
<p>
<!---->
<a name="Variables"></a>
<font size=+2><b>Variables</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
Variable names are case-sensitive. The underscore character is allowed and is often used
to enhance the readability of long variable names. C keywords like <font face="Courier" color=blue>if</font>,
<font face="Courier" color=blue>while</font>, etc. may
not be used as variable names.
<p>
Functions and global variables may not have the same name. In addition, if a local
variable is named the same as a function or a global variable, the local use takes
precedence; ie., use of the function or global variable is prevented within the scope of the
local variable.
<dl><dd>
<!---->
<a name="Declaration"></a>
<font size=+1><b>Declaration</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
In C, variables can be declared at the top level (outside of any curly braces) or at the start
of each block (a functional unit of code surrounded by curly braces). In general, a
variable declaration is of the form:
<table><tr><td><font face="Times"><dl>
   <dd><i>&lt;type&gt; &nbsp;&nbsp;&lt;variable-name&gt;</i>;    or
   <dd><i>&lt;type&gt; &nbsp;&nbsp;&lt;variable-name&gt;=&lt;initialization-data&gt;</i>;</dl></font>
</td></tr></table>
In IC, <i>&lt;<a href="#Data Types">type</a>&gt;</i> can be <font face="Courier", color=blue>int</font>,
<font face="Courier", color=blue>long</font>, <font face="Courier", color=blue>float</font>,
<font face="Courier", color=blue>char</font>, or <font face="Courier", color=blue>struct</font> <i>&lt;struct-name&gt;</i>, and
determines the <i>primary type</i> of the variable declared. This form changes somewhat when
dealing with pointer and array declarations, which are explained in a later section, but in
general this is the way you declare variables.
<p>
<!---->
<a name="Local and Global Scopes"></a>
<font size=+1><b>Local and Global Scopes</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
If a variable is declared within a function, or as an argument to a function, its binding is
<i>local</i>, meaning that the variable has existence only within that function definition.
If a variable is declared outside of a function, it is a <i>global</i> variable. It is defined for all
functions, including functions which are defined in files other than the one in which the
global variable was declared.
<p>
<!---->
<a name="Variable Initialization"></a>
<font size=+1><b>Variable Initialization</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
Local and global variables can be initialized to a value when they are declared. If no
initialization value is given, the variable is initialized to zero.
<p>
All global variable declarations must be initialized to constant values. Local variables
may be initialized to the value of arbitrary expressions including any global variables,
function calls, function arguments, or local variables which have already been initialized.
<p>
Here is a small example of how initialized declarations are used.
<pre>   <font color=blue>int</font> i=50;     <font color=darkgreen>/* <i>declare i as global integer; initial value 50</i> */</font>
   <font color=blue>long</font> j=100L;  <font color=darkgreen>/* <i>declare j as global long; initial value 100</i> */</font>
   <font color=blue>int</font> foo()
   {
     <font color=blue>int</font> x;      <font color=darkgreen>/* <i>declare x as local integer; initial value 0</i> */</font>
     <font color=blue>long</font> y=j;   <font color=darkgreen>/* <i>declare y as local integer; initial value j</i> */</font>
   }
</pre>
Local variables are initialized whenever the function containing them is executed.
Global variables are initialized whenever a reset condition occurs. Reset conditions occur
when:
<table><tr><td><ol><font face="Times">
<li>Code is downloaded;
<li>The <b>main()</b> procedure is run;
<li>System hardware reset occurs.</font>
</ol></td></tr></table>
<p>
<!---->
<a name="Persistent Global Variables"></a>
<font size=+1><b>Persistent Global Variables</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
A special persistent form of global variable, has been implemented for IC. A persistent
global variable may be initialized just like any other global variable, but its value is only
initialized when the code is downloaded and not on any other reset conditions. If no
initialization information is included for a persistent variable, its value will be initialized
to zero on download, but left unchanged on all other reset conditions.
<p>
To make a persistent global variable, prefix the type specifier with the keyword
<font face="Courier" color=blue>persistent</font>. For example, the statement
<pre>   <font color=blue>persistent int</font> i=500;
</pre>
creates a global integer called <b>i</b> with the initial value <b>500</b>.
<p>
Persistent variables keep their state when the board is turned off and on, when <b>main</b> is
run, and when system reset occurs.  Persistent variables will lose their state when code is
downloaded as a result of loading or unloading a file.  However, it is possible to read the
values of your persistent variables in IC if you are still running the same IC session from
which the code was downloaded.  In this manner you could read the final values of
calibration persistent variables, for example, and modify the initial values given to those
persistent variables appropriately.
<p>
Persistent variables were created with two applications in mind:
<table><tr><td><font face="Times"><ul>
<li>Calibration and configuration values that do not need to be re-calculated on every
reset condition.
<li>Robot learning algorithms that might occur over a period when the robot is turned
on and off.
</ul></font></td></tr></table>
</dl>
<!---->
<a name="Constants"></a>
<font size=+2><b>Constants</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
<!---->
<dl><dd>
<a name="Integer Constants"></a>
<font size=+1><b>Integer Constants</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
Integers constants may be defined in decimal integer format (e.g., <b>4053</b> or <b>-1</b>),
hexadecimal format using the "<b>0x</b>" prefix (e.g., <b>0x1fff</b>), and a non-standard but useful
binary format using the "<b>0b</b>" prefix (e.g., <b>0b1001001</b>). Octal constants using the zero
prefix are not supported.
<p>
<!---->
<a name="Long Integer Constants"></a>
<font size=+1><b>Long Integer Constants</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
Long integer constants are created by appending the suffix "<b>l</b>" or "<b>L</b>" (upper- or lower-
case alphabetic L) to a decimal integer. For example, <b>0L</b> is the long zero. Either the upper
or lower-case "<b>L</b>" may be used, but upper-case is the convention for readability.
<p>
<!---->
<a name="Floating Point Constants"></a>
<font size=+1><b>Floating Point Constants</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
Floating point numbers may use exponential notation (e.g., "<b>10e3</b>" or "<b>10E3</b>") or may
contain a decimal period. For example, the floating point zero can be given as "<b>0.</b>",
"<b>0.0</b>", or "<b>0E1</b>", but not as just "<b>0</b>". <i>Since the board has no floating point hardware,
floating point operations are much slower than integer operations, and should be used
sparingly.</i>
<p>
<!---->
<a name="Characters and String Constants"></a>
<font size=+1><b>Characters and String Constants</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
Quoted characters return their ASCII value (e.g., '<b>x</b>').
<p>
Character string constants are defined with quotation marks, e.g.,
<font face="Courier" color=red>"This is a character string."</font>.
<p>
<!---->
<a name="NULL"></a>
<font size=+1><b><font face="Courier">NULL</font></b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
The special constant <b>NULL</b> has the value of zero and can be assigned to and compared to
pointer or array variables (which will be described in later sections). In general, you
cannot convert other constants to be of a pointer type, so there are many times when
<b>NULL</b> can be useful.
<p>
For example, in order to check if a pointer has been initialized you could compare its
value to <b>NULL</b> and not try to access its contents if it was <b>NULL</b>. Also, if you had a defined
a linked list type consisting of a value and a pointer to the next element, you could look
for the end of the list by comparing the next pointer to <b>NULL</b>.
</dl>
<!---->
<a name="Data Types"></a>
<font size=+2><b>Data Types</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
IC supports the following data types:
<p>
<!---->
<dl><dd>
<a name="16-bit Integers"></a>
<font size=+1><b>16-bit Integers</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
16-bit integers are signified by the type indicator <font face="Courier" color=blue>int</font>. They are signed integers, and may
be valued from -32,768 to +32,767 decimal.
<p>
<!---->
<a name="32-bit Integers"></a>
<font size=+1><b>32-bit Integers</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
32-bit integers are signified by the type indicator <font face="Courier" color=blue>long</font>. They are signed integers, and
may be valued from -2,147,483,648 to +2,147,483,647 decimal.
<p>
<!---->
<a name="32-bit Floating Point Numbers"></a>
<font size=+1><b>32-bit Floating Point Numbers</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
Floating point numbers are signified by the type indicator <font face="Courier" color=blue>float</font>. They have
approximately seven decimal digits of precision and are valued from about 10^-38 to
10^38.
<p>
<!---->
<a name="8-bit Characters"></a>
<font size=+1><b>8-bit Characters</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
Characters are an 8-bit number signified by the type indicator <font face="Courier" color=blue>char</font>. A character's value
typically represents a printable symbol using the standard ASCII character code, but this
is not necessary; characters can be used to refer to arbitrary 8-bit numbers.
<p>
<!---->
<a name="Pointers"></a>
<p>
<font size=+1><b>Pointers</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
IC pointers are 16-bit numbers which represent locations in memory. Values in memory
can be manipulated by calculating, passing and <i>dereferencing</i> pointers representing the
location where the information is stored.
<p>
<!---->
<a name="Arrays"></a>
<p>
<font size=+1><b>Arrays</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
Arrays are used to store homogenous lists of data (meaning that all the elements of an
array have the same type). Every array has a length which is determined at the time the
array is declared. The data stored in the elements of an array can be set and retrieved in
the same manner as for other variables.
<p>
<!---->
<a name="Structures"></a>
<font size=+1><b>Structures</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
Structures are used to store non-homogenous but related sets of data. Elements of a
structure are referenced by name instead of number and may be of any supported type.
<p>
Structures are useful for organizing related data into a coherent format, reducing the
number of arguments passed to functions, increasing the effective number of values
which can be returned by functions, and creating complex data representations such as
directed graphs and linked lists.
</dl>
<!---->
<a name="PointersM"></a>
<font size=+2><b>Pointers</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
The address where a value is stored in memory is known as the pointer to that value. It is
often useful to deal with pointers to objects, but great care must be taken to insure that the
pointers used at any point in your code really do point to valid objects in memory.
<p>
Attempts to refer to invalid memory locations could corrupt your memory. Most
computing environments that you are probably used to return helpful messages like
'Segmentation Violation' or 'Bus Error' on attempts to access illegal memory.
However, you won't have this safety net on the board you are connecting to.  Invalid
pointer dereferencing is very likely to go undetected, and will likely render invalid your
data, your program, or even the pcode interpreter.
<p>
<!---->
<a name="Pointer Safety"></a>
<font size=+1><b>Pointer Safety</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
In past versions of IC, you could not return pointers from functions or have arrays of
pointers. In order to facilitate the use of structures, these features have been added to the
current version. With this change, the number of opportunities to misuse pointers have
increased. However, if you follow a few simple precautions you should do fine.
<p>
First, you should always check that the value of a pointer is not equal to <b>NULL</b> (a special
zero pointer) before you try to access it. Variables which are declared to be pointers are
initialized to <b>NULL</b>, so many uninitialized values could be caught this way.
<p>
Second, you should never use a pointer to a local variable in a manner which could cause
it to be accessed after the function in which it was declared terminates. When a function
terminates the space where its values were being stored is recycled. Therefore not only
may dereferencing such pointers return incorrect values, but assigning to those addresses
could lead to serious data corruption. A good way to prevent this is to never return the
address of a local variable from the function which declares it and never store those
pointers in an object which will live longer than the function itself (a global pointer,
array, or <font face="Courier">struct</font>). Global variables and variables local to main will not move once
declared and their pointers can be considered to be secure.
<p>
The type checking done by IC will help prevent many mishaps, but it will not catch all
errors, so be careful.
<p>
<!---->
<a name="Pointer Declaration and Use"></a>
<font size=+1><b>Pointer Declaration and Use</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
A variable which is a pointer to an object of a given type is declared in the same manner
as a regular object of that type, but with an extra * in front of the variable name.
<p>
The value stored at the location the pointer refers to is accessed by using the * operator
before the expression which calculates the pointer. This process is known as
dereferencing.
<p>
The address of a variable is calculated by using the <b>&</b> operator before that variable, array
element, or structure element reference.
<p>
There are two main differences between how you would use a variable of a given type
and a variable declared as a pointer to that type.
<p>
For the following explanation, consider <b>X</b> and <b>Xptr</b> as defined as follows:
<pre>   <font color=blue>long</font> X; <font color=blue>long</font> *Xptr;
</pre>
<ul>
<li>Space Allocation -- Declaring an object of a given type, as <b>X</b> is of type
<font face="Courier" color=blue>long</font>,
allocates the space needed to store that value. Because an IC long takes four bytes
of memory, four bytes are reserved for the value of <b>X</b> to occupy. However, a
pointer like <b>Xptr</b> does not have the same amount of space allocated for it that is
needed for an object of the type it points to. Therefore it can only safely refer to
space which has already been allocated for globals (in a special section of
memory reserved for globals) or locals (temporary storage on the stack).
<li>Initial Value -- It is always safe to refer to a non-pointer type, even if it hasn't
been initialized. However pointers have to be specifically assigned to the address
of legally allocated space or to the value of an already initialized pointer before
they are safe to use.
</ul>
So, for example, consider what would happen if the first two statements after <b>X</b> and <b>Xptr</b>
were declared were the following:
<pre>   X=50L; *Xptr=50L;
</pre>
The first statement is valid: it sets the value of <b>X</b> to <b>50L</b>. The second statement would be
valid if <b>Xptr</b> had been properly initialized, but in this case it has not. Therefore, this
statement would corrupt memory.
<p>
Here is a sequence of commands you could try which illustrate how pointers and the *
and & operators are used. It also shows that once a pointer has been set to point at a place
in memory, references to it actually share the same memory as the object it points to:
<pre>   X=50L;               <font color=darkgreen>/* <i>set the memory allocated for X to 50</i> */</font>
   Xptr=&X;             <font color=darkgreen>/* <i>set Xptr to point to memory address of X</i> */</font>
   <font color=purple>printf</font>(<font color=red>"%d "</font>,*Xptr); <font color=darkgreen>/* <i>dereference Xptr; value at address is 50</i> */</font>
   X=100L;              <font color=darkgreen>/* <i>set X to the value 100</i> */</font>
   <font color=purple>printf</font>(<font color=red>"%d "</font>,*Xptr); <font color=darkgreen>/* <i>dereference again; value is now 100</i> */</font>
   *Xptr=200L;          <font color=darkgreen>/* <i>set value at address given by Xptr to 200</i> */</font>
   <font color=purple>printf</font>(<font color=red>"%d\n"</font>,X);    <font color=darkgreen>/* <i>check that the value of X changed to 200</i> */</font>
</pre>
<p>
<!---->
<a name="Passing Pointers as Arguments"></a>
<font size=+1><b>Passing Pointers as Arguments</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
Pointers can be passed to functions and functions can change the values of the variables
that are pointed at. This is termed <i>call-by-reference</i>; a reference, or pointer, to a variable
is given to the function that is being called. This is in contrast to <i>call-by-value</i>, the
standard way that functions are called, in which the value of a variable is given the to
function being called.
<p>
The following example defines an <b>average_sensor</b> function which takes a port
number and a pointer to an integer variable. The function will average the sensor and
store the result in the variable pointed at by <b>result</b>.
<p>
Prefixing an argument name with * declares that the argument is a pointer.
<pre>   <font color=blue>void</font> average_sensor(<font color=blue>int</font> port, <font color=blue>int</font> *result)
   {
      <font color=blue>int</font> sum = 0;
      <font color=blue>int</font> i;
      <font color=blue>for</font> (I = 0; I &lt; 10; i++) sum += <font color=purple>analog</font>(port);
      *result =  sum/10;
   }
</pre>
Notice that the function itself is declared as a <font face="Courier" color=blue>void</font>. It does not need to return anything,
because it instead stores its answer in the memory location given by the pointer variable
that is passed to it.
<p>
The pointer variable is used in the last line of the function. In this statement, the answer
sum/10 is stored at the location pointed at by result. Notice that the * is used to assign a
value to the location pointed by result.
<p>
<!---->
<a name="Returning Pointers from Functions"></a>
<font size=+1><b>Returning Pointers from Functions</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
Pointers can also be returned from functions. Functions are defined to return pointers by
preceeding the name of the function with a star, just like any other type of pointer
declaration.
<pre>   <font color=blue>int</font> right,left;
   <font color=blue>int</font> *dirptr(<font color=blue>int</font> dir)
   {
       <font color=blue>if</font> (dir==0) {
         <font color=blue>return</font>(&right);
       }
       <font color=blue>if</font> (dir==1) {
          <font color=blue>return</font>(&left);
       }
       <font color=blue>return</font>(NULL);
   }
</pre>
The function <b>dirptr</b> returns a pointer to the global <b>right</b> when its argument <b>dir</b> is 0, a
pointer to <b>left</b> when its argument is 1, and <b>NULL"</b> if its argument is other than 0 or 1.
<p>
<!---->
<a name="Arrays"></a>
<font size=+2><b>Arrays</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
IC supports arrays of characters, integers, long integers, floating-point numbers,
structures, pointers, and array pointers (multi-dimensional arrays). While unlike regular C
arrays in a number of respects, they can be used in a similar manner. The main reasons
that arrays are useful are that they allow you to allocate space for many instances of a
given type, send an arbitrary number of values to functions, and provide the means for
iterating over a set of values.
<p>
Arrays in IC are different and incompatible with arrays in other versions of C. This
incompatibility is caused by the fact that references to IC arrays are checked to insure
that the reference is truly within the bounds of that array. In order to accomplish this
checking in the general case, it is necessary that the size of the array be stored with the
contents of the array. <i>It is important to remember that an array of a given type and a
pointer to the same type are incompatible types in IC, whereas they are largely
interchangeable in regular C</i>.
<p>
<!---->
<a name="Declaring and Initializing Arrays"></a>
<font size=+1><b>Declaring and Initializing Arrays</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
Arrays are declared using square brackets. The following statement declares an array of
ten integers:
<pre>   <font color=blue>int</font> foo[10];
</pre>
In this array, elements are numbered from 0 to 9. Elements are accessed by enclosing the
index number within square brackets: <b>foo[4]</b> denotes the fifth element of the array foo
(since counting begins at zero).
<p>
Arrays are initialized by default to contain all zero values. Arrays may also be initialized
at declaration by specifying the array elements, separated by commas, within curly
braces. If no size value is specified within the square brackets when the array is declared
but initialization information is given, the size of the array is determined by the number
of elements given in the declaration. For example,
<pre>   <font color=blue>int</font> foo[]= {0, 4, 5, -8,  17, 301};
</pre>
creates an array of six integers, with <b>foo[0]</b> equaling <b>0</b>, <b>foo[1]</b> equaling <b>4</b>, etc.
<p>
If a size is specified and initialization data is given, the length of the initialization data
may not exceed the specified length of the array or an error results. If, on the other hand,
you specify the size and provide fewer initialization elements than the total length of the
array, the remaining elements are initialized to zero.
<p>
Character arrays are typically text strings. There is a special syntax for initializing arrays
of characters. The character values of the array are enclosed in quotation marks:
<pre>   <font color=blue>char</font> string[]= <font color=red>"Hello there"</font>;
</pre>
This form creates a character array called <b>string</b> with the ASCII values of the specified
characters. In addition, the character array is terminated by a zero. Because of this zero-termination, the character array can be treated as a string for purposes of printing (for
example). Character arrays can be initialized using the curly braces syntax, but they will
not be automatically null-terminated in that case. In general, printing of character arrays
that are not null-terminated will cause problems.
<p>
<!---->
<a name="Passing Arrays as Arguments"></a>
<font size=+1><b>Passing Arrays as Arguments</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
When an array is passed to a function as an argument, the array's pointer is actually
passed, rather than the elements of the array. If the function modifies the array values, the
array will be modified, since there is only one copy of the array in memory.
<p>
In normal C, there are two ways of declaring an array argument: as an array or as a
pointer to the type of the array's elements.  In IC array pointers are incompatible with
pointers to the elements of an array so such arguments can only be declared as arrays.
<p>
As an example, the following function takes an index and an array, and returns the array
element specified by the index:
<pre>   <font color=blue>int</font> retrieve_element(<font color=blue>int</font> index, <font color=blue>int</font> array[])
   {
       <font color=blue>return</font> array[index];
   }
</pre>
Notice the use of the square brackets to declare the argument array as a pointer to an
array of integers.
<p>
When passing an array variable to a function, you are actually passing the value of the
array pointer itself and not one of its elements, so no square brackets are used.
<pre>   <font color=blue>void</font> foo()
   {
       <font color=blue>int</font> array[10];
       retrieve_element(3, array);
   }
</pre>
<!---->
<a name="Multi-dimensional Arrays"></a>
<font size=+1><b>Multi-dimensional Arrays</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
A two-dimensional array is just like a single dimensional array whose elements are one-
dimensional arrays. Declaration of a two-dimensional array is as follows:
<pre>   <font color=blue>int</font> k[2][3];
</pre>
The number in the first set of brackets is the number of 1-D arrays of <font face="Courier" color=blue>int</font>. The number in
the second set of brackets is the length of each of the 1-D arrays of <font face="Courier" color=blue>int</font>. In this example,
<b>k</b> is an array containing two 1-D arrays; <b>k[0]</b> is a 1-D array of <font face="Courier">color=blue>int</font> of length 3;
<b>k[0][1]</b> is an <font face="Courier">color=blue>int</font>. Arrays of with any number of dimensions can be generalized from
this example by adding more brackets in the declaration.
<p>
<!---->
<a name="Determining the size of Arrays at Runtime"></a>
<font size=+1><b>Determining the size of Arrays at Runtime</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
An advantage of the way IC deals with arrays is that you can determine the size of arrays
at runtime. This allows you to do size checking on an array if you are uncertain of its
dimensions and possibly prevent your program from crashing.
<p>
<i>Since </i><font face="Courier"><b>_array_size</b></font> <i>is not a standard C feature, code written using this primitive will
only be able to be compiled with IC</i>.
<p>
The <b>_array_size</b> primitive returns the size of the array given to it regardless of the
dimension or type of the array. Here is an example of declarations and interaction with
the <b>_array_size</b> primitive:
<pre>   <font color=blue>int</font> i[4]={10,20,30};
   <font color=blue>int</font> j[3][2]={{1,2},{2,4},{15}};
   <font color=blue>int</font> k[2][2][2];
   _array_size(i);    <font color=darkgreen>/* <i>returns 4</i> */</font>
   _array_size(j);    <font color=darkgreen>/* <i>returns 3</i> */</font>
   _array_size(j[0]); <font color=darkgreen>/* <i>returns 2</i> */</font>
   _array_size(k);    <font color=darkgreen>/* <i>returns 2</i> */</font>
   _array_size(k[0]); <font color=darkgreen>/* <i>returns 2</i> */</font>
</pre>
<!---->
<a name="Uploading Arrays"></a>
<font size=+1><b>Uploading Arrays</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
When an executing program is paused or has finished, IC can upload the values stored
in any global array via the serial port.  This permits collecting and recording data
for purposes such as experimentation or calibration.
<p>
The IC upload array capability is accessed using the tools tab.  When upload array is
activated, it lists all globally declared arrays.  When an array is selected, it is
opened in a (modal) view window.  The array can be copied to the clipboard, or saved
to a TXT or CSV (comma separated values) file for import to analysis software.
<p>
<!---->
<a name="Structures2"></a>
<font size=+2><b>Structures</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
Structures are used to store non-homogenous but related sets of data. Elements of a
structure are referenced by name instead of number and may be of any supported type.
Structures are useful for organizing related data into a coherent format, reducing the
number of arguments passed to functions, increasing the effective number of values
which can be returned by functions, and creating complex data representations such as
directed graphs and linked lists.
<p>
The following example shows how to define a structure, declare a variable of structure
type, and access its elements.
<pre>   <font color=blue>struct</font> foo
   {
       <font color=blue>int</font> i;
       <font color=blue>int</font> j;
   };
   <font color=blue>struct</font> foo f1;
   <font color=blue>void</font> set_f1(<font color=blue>int</font> i,<font color=blue>int</font> j)
   {
       f1.i=i;
       f1.j=j;
   }
   <font color=blue>void</font> get_f1(<font color=blue>int</font> *i,<font color=blue>int</font> *j)
   {
       *i=f1.i;
       *j=f1.j;
   }
</pre>
The first part is the structure definition. It consists of the keyword
<font face="Courier" color=blue>struct</font>, followed by
the name of the structure (which can be any valid identifier), followed by a list of named
elements in curly braces. This definition specifies the structure of the type <font face="Courier" color=blue>struct</font> <b>foo</b>.
Once there is a definition of this form, you can use the type  <font face="Courier" color=blue>struct</font> <b>foo</b>  just like any
other type. The line
<pre>    <font color=blue>struct</font> foo f1;
</pre>
is a global variable declaration which declares the variable <b>f1</b> to be of type <font face="Courier" color=blue>struct</font>
<b>foo</b>.
<p>
The dot operator is used to access the elements of a variable of structure type. In this
case, <b>f1.i</b> and <b>f1.j</b> refer to the two elements of <b>f1</b>. You can treat the quantities <b>f1.i</b>
and <b>f1.j</b> just as you would treat any variables of type <font face="Courier" color=blue>int</font> (the type of the elements was
defined in the structure declaration at the top to be <font face="Courier" color=blue>int</font>).
<p>
Pointers to structure types can also be used, just like pointers to any other type. However,
with structures, there is a special short-cut for referring to the elements of the structure
pointed to.
<pre>   <font color=blue>struct</font> foo *fptr;
   <font color=blue>void</font> main()
   {
       fptr=&f1;
       fptr-&gt;i=10;
       fptr-&gt;j=20;
   }
</pre>
In this example, <b>fptr</b> is declared to be a pointer to type <font face="Courier" color=blue>struct</font> <b>foo</b>.  In main, it is set to
point to the global <b>f1</b> defined above. Then the elements of the structure pointed to by <b>fptr</b>
(in this case these are the same as the elements of <b>f1</b>), are set. The arrow operator is used
instead of the dot operator because fptr is a pointer to a variable of type <font face="Courier" color=blue>struct</font> <b>foo</b>. Note
that <b>(*fptr).i</b> would have worked just as well as <b>fptr<font face="Courier">-&gt;</font>i</b>, but it would have been
clumsier.
<p>
Note that only pointers to structures, not the structures themselves, can be passed to or
returned from functions.
<p>
<!---->
<a name="Complex Initialization examples"></a>
<font size=+2><b>Complex Initialization examples</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
Complex types -- arrays and structures -- may be initialized upon declaration with a
sequence of constant values contained within curly braces and separated by commas.
<p>
Arrays of character may also be initialized with a quoted string of characters.
<p>
For initialized declarations of single dimensional arrays, the length can be left blank and
a suitable length based on the initialization data will be assigned to it. <i>Multi-dimensional
arrays must have the size of all dimensions specified when the array is declared</i>. If a
length is specified, the initialization data may not overflow that length in any dimension
or an error will result. However, the initialization data may be shorter than the specified
size and the remaining entries will be initialized to 0.
<p>
Following is an example of legal global and local variable initializations:
<pre>   <font color=darkgreen>/* <i>declare many globals of various types</i> */</font>
   <font color=blue>int</font> i=50;
   <font color=blue>int</font> *ptr=NULL;
   <font color=blue>float</font> farr[3]={ 1.2, 3.6, 7.4 };
   <font color=blue>int</font> tarr[2][4]={ { 1, 2, 3, 4 }, { 2, 4, 6, 8} };
   <font color=blue>char</font> c[]=<font color=red>"Hi there how are you?"</font>;
   <font color=blue>char</font> carr[5][10]={<font color=red>"Hi"</font>,<font color=red>"there"</font>,<font color=red>"how"</font>,<font color=red>"are"</font>,<font color=red>"you"</font>};
   <font color=blue>struct</font> bar
   {
      <font color=blue>int</font> i;
      <font color=blue>int</font> *p;
      <font color=blue>long</font> j;
   } b={5, NULL, 10L};
   <font color=blue>struct</font> bar barr[2] = { { 1, NULL, 2L }, { 3 } };
   /* declare locals of various types */
   <font color=blue>int</font> foo()
   {
      <font color=blue>int</font> x;             <font color=darkgreen>/* <i>local variable x with initial value 0</i> */</font>
      <font color=blue>int</font> y= tarr[0][2]; <font color=darkgreen>/* <i>local variable y with initial value 3</i> */</font>
      <font color=blue>int</font> *iptr=&i;      <font color=darkgreen>/* <i>local pointer to integer
                            which points to the global i</i> */</font>
      <font color=blue>int</font> larr[2]={10,20};  <font color=darkgreen>/* <i>local array larr
                               with elements 10 and 20</i> */</font>
      <font color=blue>struct</font> bar lb={5,NULL,10L};  <font color=darkgreen>/* <i>local variable of type
                                      struct bar with i=5 and j=10 </i>*/</font>
      <font color=blue>char</font> lc[]=carr[2];    <font color=darkgreen>/* <i>local string lc with
                               initial value "how"</i> */</font>
      ...
   }
</pre>
<!---->
<a name="Statements and Expressions"></a>
<font size=+3><b>Statements and Expressions</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
Operators act upon objects of a certain type or types and specify what is to be done to
them. Expressions combine variables and constants to create new values. Statements are
expressions, assignments, function calls, or control flow statements which make up C
programs.
<p>
<!---->
<a name="Operators"></a>
<font size=+2><b>Operators</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
Each of the data types has its own set of operators that determine which operations may
be performed on them.
<p>
<!---->
<a name="Integer Operations"></a>
<font size=+2><b>Integer Operations</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
The following operations are supported on integers:
<ul>
  <li><b>Arithmetic</b>. addition <font face="Courier">+</font>, subtraction <font face="Courier">-</font>,
         multiplication <font face="Courier">*</font>, division <font face="Courier">/</font>.
  <li><b>Comparison</b>. greater-than <font face="Courier">&gt;</font>, less-than <font face="Courier">&lt;</font>,
         equality <font face="Courier">==</font>, greater-than-equal <font face="Courier">&gt;=</font>,
         less-than-equal <font face="Courier">&lt;=</font>.
  <li><b>Bitwise Arithmetic</b>. bitwise-OR <font face="Courier">|</font>, bitwise-AND <font face="Courier">&</font>,
         bitwise-exclusive-OR <font face="Courier">^</font>, bitwise-NOT <font face="Courier">~</font>.
  <li><b>Boolean Arithmetic</b>. logical-OR <font face="Courier">||</font>, logical-AND <font face="Courier">&&</font>,
         logical-NOT <font face="Courier">!</font>. <br>
         When a C statement uses a boolean value (for example, <font face="Courier" color=blue>if</font>), it takes the integer zero as
         meaning false, and any integer other than zero as meaning true. The boolean
         operators return zero for false and one for true. Boolean operators <font face="Courier">&&</font> and <font face="Courier">||</font> will
         stop executing as soon as the truth of the final expression is determined. For
         example, in the expression <font face="Courier">a && b</font>,
         if <font face="Courier">a</font> is false, then <font face="Courier">b</font> does not need to be
         evaluated because the result must be false. The <font face="Courier">&&</font> operator therefore will not
         evaluate <font face="Courier">b</font>.</ul>

<!---->
<a name="Long Integers"></a>
<font size=+2><b>Long Integers</b></font> &nbsp;&nbsp;<font size=1> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p></font>
A subset of the operations implemented for integers are implemented for long integers:
arithmetic addition +, subtraction -, and multiplication *, and the integer comparison
operations. Bitwise and boolean operations and division are not supported.
<p>
<!---->
<a name="Floating Point Numbers"></a>
<font size=+2><b>Floating Point Numbers</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
IC uses a package of public-domain floating point routines distributed by Motorola. This
package includes arithmetic, trigonometric, and logarithmic functions. Since floating
point operations are implemented in software, they are much slower than the integer
operations; we recommend against using floating point if you are concerned about
performance.
<p>
The following operations are supported on floating point numbers:
<table><tr><td><font face="Times"><ul>
<li><b>Arithmetic</b>. addition <font face="Courier">+</font>, subtraction <font face="Courier">-</font>,
         multiplication <font face="Courier">*</font>, division <font face="Courier">/</font>.
<li><b>Comparison</b>. greater-than <font face="Courier">&gt;</font>, less-than <font face="Courier">&lt;</font>,
         equality <font face="Courier">==</font>, greater-than-equal <font face="Courier">&gt;=</font>,
         less-than-equal <font face="Courier">&lt;=</font>.
<li><b>Built-in Math Functions</b>. A set of trigonometric, logarithmic, and exponential
functions is supported. For details, go to the
<a href="#Library Function Descriptions">Library Function Descriptions</a>.
These functions are included among those itemized as "Math" functions.</ul></font>
</td></tr></table>
<!---->
<a name="Characters"></a>
<font size=+2><b>Characters</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
Characters are only allowed in character arrays. When a cell of the array is referenced, it
is automatically coerced into a integer representation for manipulation by the integer
operations. When a value is stored into a character array, it is coerced from a standard 16-
bit integer into an 8-bit character (by truncating the upper eight bits).
<p>
<!---->
<a name="Assignment Operators and Expressions"></a>
<font size=+3><b>Assignment Operators and Expressions</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
The basic assignment operator is <font face="Courier">=</font>. The following statement adds 2 to the value of <font face="Courier">a</font>.
<pre>   a = a + 2;
</pre>
The abbreviated form
<pre>   a += 2;
</pre>
could also be used to perform the same operation.

All of the following binary operators can be used in this fashion:
<pre>   +   -   *   /   %   <<   >>   &   ^   |
</pre>
<!---->
<a name="Increment and Decrement Operators"></a>
<font size=+3><b>Increment and Decrement Operators</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
The increment operator "<font face="Courier">++</font>" increments the named variable. For example, the
construction "<font face="Courier">a++</font>" is equivalent to "<font face="Courier">a= a+1</font>" or "<font face="Courier">a+= 1</font>".

A statement that uses an increment operator has a value. For example, the statement
<pre>   a= 3; <font color=purple>printf</font>(<font color=red>"a=%d a+1=%d\n"</font>, a, ++a);
</pre>
will display the text "<font face="Courier">a=3 a+1=4</font>".

If the increment operator comes after the named variable, then the value of the statement
is calculated after the increment occurs. So the statement
<pre>   a= 3; <font color=purple>printf</font>(<font color=red>"a=%d a+1=%d\n"</font>, a, a++);
</pre>
would display "<font face="Courier">a=3 a+1=3</font>" but would finish with a set to 4.
The decrement operator "<font face="Courier">--</font>" is used in the same fashion as the increment operator.
<p>
<!---->
<a name="Data Access Operators"></a>
<font size=+3><b>Data Access Operators</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
<b><font face="Courier">&</font></b>
<table><tr><td><font face="Times"><dl><dd>A single ampersand preceding a variable, an array reference, or a structure element
reference returns a pointer to the location in memory where that information is being
stored. This should not be used on arbitrary expressions as they do not have a stable
place in memory where they are being stored.</font></td></tr></table>
<b><font face="Courier">*</font></b>
<table><tr><td><font face="Times"><dl><dd>A single * preceeding an expression which evaluates to a pointer returns the value
which is stored at that address. This process of accessing the value stored within a
pointer is known as <i>dereferencing</i>.</font></td></tr></table>
<font face="Courier"><b>[</b>&lt;</font><i>expr</i><font face="Courier">&gt;<b>]</b></font>
<table><tr><td><font face="Times"><dl><dd>An expression in square braces following an expression which evaluates to an array
(an array variable, the result of a function which returns an array pointer, etc.) checks
that the value of the expression falls within the bounds of the array and references
that element.</font></td></tr></table>
<b><font face="Courier">.</font></b>
<table><tr><td><font face="Times"><dl><dd>A dot between a structure variable and the name of one of its fields returns the value
stored in that field.</font></td></tr></table>
<b><font face="Courier">-&gt;</font></b>
<table><tr><td><font face="Times"><dl><dd>An arrow between a pointer to a structure and the name of one of its fields in that
structure acts the same as a dot does, except it acts on the structure pointed at by its
left hand side. Where <b>f</b> is a structure of a type with <b>i</b> as an element name, the two
expressions <font face="Courier">f.i</font> and <font face="Courier">(&f)->i</font> are equivalent.</font></td></tr></table>
<p>
<!---->
<a name="Precedence and Order of Evaluation"></a>
<font size=+3><b>Precedence and Order of Evaluation</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
The following table summarizes the rules for precedence and associativity for the C operators.
Operators listed earlier in the table have higher precedence; operators on the same line of the table
have equal precedence.
<table><tr><td><dl><dd>
<table border=1><tr><td align=center><font face="Times"><b>Operator</b></font></td><td>&nbsp; <b><font face="Times">Associativity</b> &nbsp;</font></td></tr>
<tr><td><font face="Courier">&nbsp; () []</font></td><td align=center><font face="Times">left to right</font></td></tr>
<tr><td><font face="Courier">&nbsp; ! ~ ++ -- - (&lt;</font><i>type</i><font face="Courier">&gt;) &nbsp;</font></td><td align=center><font face="Times">right to left</font></td></tr>
<tr><td><font face="Courier">&nbsp; * / %</font></td><td align=center><font face="Times">left to right</font></td></tr>
<tr><td><font face="Courier">&nbsp; + -</font></td><td align=center><font face="Times">left to right</font></td></tr>
<tr><td><font face="Courier">&nbsp; &lt;&lt; &gt;&gt;</font></td><td align=center><font face="Times">left to right</font></td></tr>
<tr><td><font face="Courier">&nbsp; &lt; &lt;= &gt; &gt;=</font></td><td align=center><font face="Times">left to right</font></td></tr>
<tr><td><font face="Courier">&nbsp; == !=</font></td><td align=center><font face="Times">left to right</font></td></tr>
<tr><td><font face="Courier">&nbsp; &</font></td><td align=center><font face="Times">left to right</font></td></tr>
<tr><td><font face="Courier">&nbsp; ^</font></td><td align=center><font face="Times">left to right</font></td></tr>
<tr><td><font face="Courier">&nbsp; |</font></td><td align=center><font face="Times">left to right</font></td></tr>
<tr><td><font face="Courier">&nbsp; &&</font></td><td align=center><font face="Times">left to right</font></td></tr>
<tr><td><font face="Courier">&nbsp; ||</font></td><td align=center><font face="Times">right to left</font></td></tr>
<tr><td><font face="Courier">&nbsp; = += -=</font> etc.</td><td align=center><font face="Times">right to left</font></td></tr>
<tr><td><font face="Courier">&nbsp; ,</font></td><td align=center><font face="Times">left to right</font></td></tr>
</table>
<td>
</td>
</td></tr></table>
<!---->
<p>
<a name="Control Flow"></a>
<font size=+3><b>Control Flow</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>

IC supports most of the standard C control structures. One notable exception is the switch
statement, which is not supported.
<p>
<!---->
<a name="Statements and Blocks"></a>
<font size=+2><b>Statements and Blocks</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
A single C statement is ended by a semicolon. A series of statements may be grouped
together into a <i>block</i> using curly braces. Inside a block, local variables may be defined.  Blocks may be
used in place of statements in the control flow constructs.
<p>
<!---->
<a name="If-Else"></a>
<font size=+2><b>If-Else</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>

The <font face="Courier" color=blue>if else</font> statement is used to make decisions. The syntax is:
<pre>   <font color=blue>if</font> (&lt;<font face="Times"><i>expression</i></font>&gt;)
       &lt;<font face="Times"><i>statement-1</i></font>&gt;
   <font color=blue>else</font>
       &lt;<font face="Times"><i>statement-2</i></font>&gt;
</pre>
&lt;<i>expression</i>&gt; is evaluated; if it is not equal to zero (e.g., logic true), then
&lt;<i>statement-1</i>&gt; is executed.
<p>
The <font face="Courier" color=blue>else</font> clause is optional. If the
<font face="Courier" color=blue>if</font> part of the statement did not execute, and the
<font face="Courier" color=blue>else</font> is present, then &lt;<i>statement-2</i>&gt; executes.
<p>
<!---->
<a name="While"></a>
<font size=+2><b>While</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
The syntax of a <font face="Courier" color=blue>while</font> loop is the following:
<pre>   <font color=blue>while</font> (&lt;<font face="Times"><i>expression</i></font>&gt;)
       &lt;<font face="Times"><i>statement</i></font>&gt;
</pre>
<font face="Courier" color=blue>while</font> begins by evaluating &lt;<i>expression</i>&gt;. If it is false, then
&lt;<i>statement</i>&gt; is skipped. If it
is true, then &lt;<i>statement</i>&gt; is evaluated. Then the expression is evaluated again, and the
same check is performed. The loop exits when &lt;<i>expression</i>&gt; becomes zero.
<p>
One can easily create an infinite loop in C using the <font face="Courier" color=blue>while</font> statement:
<pre>   <font color=blue>while</font> (1)
      &lt;<font face="Times"><i>statement</i></font>&gt;
</pre>
<p>
<!---->
<a name="For"></a>
<font size=+2><b>For</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
The syntax of a <font face="Courier" color=blue>for</font> loop is the following:
<pre>   <font color=blue>for</font> (&lt;<font face="Times"><i>expr-1</i></font>&gt;;&lt;<font face="Times"><i>expr-2</i></font>&gt;;&lt;<font face="Times"><i>expr-3</i></font>&gt;)
      &lt;<font face="Times"><i>statement</i></font>&gt;
</pre>
The <font face="Courier" color=blue>for</font> construct is equivalent to
the following construct using <font face="Courier" color=blue>while</font>:
<pre>   &lt;<font face="Times"><i>expr-1</i></font>&gt;;
   <font face="Courier" color=blue>while</font> (&lt;<font face="Times"><i>expr-2</i></font>&gt;)
   {
      &lt;<font face="Times"><i>statement</i></font>&gt;
      &lt;<font face="Times"><i>expr-3</i></font>&gt;;
   }
   </pre>
Typically, &lt;<i>expr-1</i>&gt; is an assignment, &lt;<i>expr-2</i>&gt;
is a relational expression, and &lt;<i>expr-3</i>&gt;
is an increment or decrement of some manner. For example, the following code counts
from 0 to 99, printing each number along the way:
<pre>   <font color=blue>int</font> i;
   <font color=blue>for</font> (i = 0; i &lt; 100; i++)
       <font color=purple>printf</font>("%d\n", i);
</pre>
<!---->
<a name="Break"></a>
<font size=+2><b>Break</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
Use of the <font face="Courier" color=blue>break</font> statement provides an early exit from a
<font face="Courier" color=blue>while</font> or a <font face="Courier" color=blue>for</font> loop.
<p>
<!---->
<a name="LCD Screen Printing"></a>
<font size=+3><b>LCD Screen Printing</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
IC has a version of the C function <font face="Courier" color=purple>printf</font> for formatted printing to the LCD screen.
<p>
The syntax of <font face="Courier" color=purple>printf</font> is the following:
<pre>   <font color=purple>printf</font>(&lt;<font face="Times"><i>format-string</i></font>&gt;, &lt;<font face="Times"><i>arg-1</i></font>&gt; , ... , &lt;<font face="Times"><i>arg-N</i></font>&gt;);
</pre>
This is best illustrated by some examples.
<p>
<!---->
<a name="Printing Examples"></a>
<font size=+2><b>Printing Examples</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
<!---->
<a name="Printing a message"></a>
<font size=+1><b>Example 1: Printing a message</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">PM Index</a></font>
<p>
The following statement prints a text string to the screen.
<table><tr><td><pre>   <font color=purple>printf</font>(<font color=red>"Hello, world!\n"</font>);</pre>
</td></tr></table>
In this example, the format string is simply printed to the screen.
The character <font face="Courier"><b>\n</b></font> at the end of the string signifies end-of-line. When an end-of-line
character is printed, the LCD screen will be cleared when a subsequent character is
printed. Thus, most <font face="Courier" color=purple>printf</font> statements are terminated by a
<font face="Courier"><b>\n</b></font>.
<p>
<!---->
<a name="Printing a number"></a>
<font size=+1><b>Example 2: Printing a number</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
The following statement prints the value of the integer variable x with a brief message.
<table><tr><td><pre>   <font color=purple>printf</font>(<font color=red>"Value is %d\n"</font>, x);</pre>
</td></tr></table>
The special form <font face="Courier"><b>%d</b></font> is used to format the printing of an integer in decimal format.
<p>
<!---->
<a name="Printing a number in binary"></a>
<font size=+1><b>Example 3: Printing a number in binary</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
The following statement prints the value of the integer variable x as a binary number.
<table><tr><td><pre>   <font color=purple>printf</font>(<font color=red>"Value is %b\n"</font>, x);</pre>
</td></tr></table>
The special form <font face="Courier"><b>%b</b></font> is used to format the printing of an integer in binary format. Only the
low byte of the number is printed.
<p>
<!---->
<a name="Printing a floating point number"></a>
<font size=+1><b>Example 4: Printing a floating point number</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
The following statement prints the value of the floating point variable <font face="Courier">n</font> as a floating
point number.
<table><tr><td><pre>   <font color=purple>printf</font>(<font color=red>"Value is %f\n"</font>, n);</pre>
</td></tr></table>
The special form <font face="Courier"><b>%f</b></font> is used to format the printing of floating point number.
<p>
<!---->
<a name="Printing two numbers in hexadecimal format"></a>
<font size=+1><b>Example 5: Printing two numbers in hexadecimal format</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
<table><tr><td><pre>   <font color=purple>printf</font>(<font color=red>"A=%x  B=%x\n"</font>, a, b);</pre>
</td></tr></table>
The form <font face="Courier"><b>%x</b></font> formats an integer to print in hexadecimal.
<p>
<!---->
<a name="Formatting Command Summary"></a>
<font size=+2><b>Formatting Command Summary</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
<table><tr><td><dl><dd>
<table border=1><tr><td align=center><font face="Times"><b>&nbsp;Format Command&nbsp;</b></font></td><td align=center><font face="Times"><b>Data Type</b></font></td><td align=center><b>Description</b></td></tr>
<tr><td><font face="Courier">&nbsp; %d </font></td><td><font face="Courier" color=blue>&nbsp; int </font></td><td><font face="Times">&nbsp; decimal number </font></td></tr>
<tr><td><font face="Courier">&nbsp; %x </font></td><td><font face="Courier" color=blue>&nbsp; int </font></td><td><font face="Times">&nbsp; hexadecimal number </font></td></tr>
<tr><td><font face="Courier">&nbsp; %b </font></td><td><font face="Courier" color=blue>&nbsp; int </font></td><td><font face="Times">&nbsp; low byte as binary number </font></td></tr>
<tr><td><font face="Courier">&nbsp; %c </font></td><td><font face="Courier" color=blue>&nbsp; int </font></td><td><font face="Times">&nbsp; low byte as ASCII character &nbsp;</font></td></tr>
<tr><td><font face="Courier">&nbsp; %f </font></td><td><font face="Courier" color=blue>&nbsp; float </font></td><td><font face="Times">&nbsp; floating point number </font></td></tr>
<tr><td><font face="Courier">&nbsp; %s </font></td><td><font face="Courier"><font color=blue>&nbsp; char</font> <font face="Times">array</font> &nbsp;</font></td><td><font face="Times">&nbsp; char array (string) </font></td></tr>
</table></dl>
</td></tr></table>
<b>Special Notes</b>
<table><tr><td><font face="Times"><ul>
<li>Depending on the display being used, the final character position of the LCD screen may be used as a system "heartbeat." This
character continuously blinks between a large and small heart when the board is
operating properly. If the character stops blinking, the board has failed.
<li>When using a two-line LCD display, the <font face="Courier"><font color=purple>printf</font>()</font> command treats the display as a single
longer line.
<li>For 1 or 2 line displays any excess text is truncated.
<li>Printing of long integers is not presently supported.
</font></td></tr></table>
<p>
<!---->
<a name="Preprocessor"></a>
<font size=+3><b>Preprocessor</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
The preprocessor processes a file before it is sent to the compiler. The IC preprocessor
allows definition of macros, and conditional compilation of sections of code. Using
preprocessor macros for constants and function macros can make IC code more efficient
as well as easier to read. Using <font face="Courier" color=blue>#if</font> to conditionally compile code can be very useful, for
instance, for debugging purposes.
<p>
The special preprocessor command <font face="Courier" color=blue>#use</font> has been included to allow programs to cause a
program to download to initiate the download of stored programs that are not in the IC
library.  For example,  suppose you have a set of stored programs in a file named
"<font face="Courier">mylib.ic</font>", some of which you need for your current program to work.
<pre>   <font color=darkgreen>/* <i>load my library</i> */</font>
   <font color=blue>#use</font> <font color=red>"mylib.ic"</font>

   <font color=blue>void</font> main()
   {
       <font color=blue>char</font> s[32] = <font color=red>"text string wrapping badly\n"</font>;
       fix (s);    <font color=darkgreen>/* <i>apply my fix function to s and print it</i> */</font>
       <font color=purple>printf</font>(s);
   }
</pre>
<!---->
<a name="Preprocessor Macros"></a>
<font size=+2><b>Preprocessor Macros</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
Preprocessor macros are defined by using the <font face="Courier" color=blue>#define</font> preprocessor directive at the start
of a line. A macro is local to the file in which it is defined. The following example shows how to define preprocessor macros.
<pre>  <font color=blue>#define</font> RIGHT_MOTOR 0
  <font color=blue>#define</font> LEFT_MOTOR  1
  <font color=blue>#define</font> GO_RIGHT(power) (<font color=purple>motor</font>(RIGHT_MOTOR,(power)))
  <font color=blue>#define</font> GO_LEFT(power)  (<font color=purple>motor</font>(LEFT_MOTOR,(power)))
  <font color=blue>#define</font> GO(left,right) {GO_LEFT(left); GO_RIGHT(right);}
  <font color=blue>void</font> main()
  {
      GO(0,0);
  }
</pre>
Preprocessor macro definitions start with the <font face="Courier" color=blue>#define</font> directive at the start of a line, and
continue to the end of the line. After <font face="Courier" color=blue>#define</font> is the name of the macro, such as
<b>RIGHT_MOTOR</b>. If there is a parenthesis directly after the name of the macro, such as the
<b>GO_RIGHT</b> macro has above, then the macro has arguments. The <b>GO_RIGHT</b> and
<b>GO_LEFT</b> macros each take one argument. The GO macro takes two arguments. After the
name and the optional argument list is the body of the macro.
<p>
Each time a macro is invoked, it is replaced with its body. If the macro has arguments,
then each place the argument appears in the body is replaced with the actual argument
provided.
<p>
Invocations of macros without arguments look like global variable references.
Invocations of macros with arguments look like calls to functions. To an extent, this is
how they act. However, macro replacement happens before compilation, whereas global
references and function calls happen at run time. Also, function calls evaluate their
arguments before they are called, whereas macros simply perform text replacement. For
example, if the actual argument given to a macro contains a function call, and the macro
instantiates its argument more than once in its body, then the function would be called
multiple times, whereas it would only be called once if it were being passed as a function
argument instead.
<p>
Appropriate use of macros can make IC programs and easier to read. It allows constants
to be given symbolic names without requiring storage and access time as a global would.
It also allows macros with arguments to be used in cases when a function call is desirable
for abstraction, without the performance penalty of calling a function.
<p>
<!---->
<a name="Conditional compilation"></a>
<font size=+2><b>Conditional compilation</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
It is sometimes desirable to conditionally compile code. The primary example of this is
that you may want to perform debugging output sometimes, and disable it at other times.
The IC preprocessor provides a convenient way of doing this by using the <font face="Courier" color=blue>#ifdef</font>
directive.
<pre>   <font color=blue>void</font> go_left(<font color=blue>int</font> power)
   {
       GO_LEFT(power);
   <font color=blue>#ifdef</font> DEBUG
       <font color=purple>printf</font>(<font color=red>"Going Left\n"</font>);
       <font color=purple>beep</font>();
   <font color=blue>#endif</font>
   }
</pre>
In this example, when the macro <b>DEBUG</b> is defined, the debugging message "Going Left"
will be printed and the board will beep each time <b>go_left</b> is called. If the macro is not
defined, the message and beep will not happen. Each <font face="Courier" color=blue>#ifdef</font> must be follwed by an
<font face="Courier" color=blue>#endif</font> at the end of the code which is being conditionally compiled. The macro to be
checked can be anything, and <font face="Courier" color=blue>#ifdef</font> blocks may be nested.
<p>
Unlike regular C preprocessors, macros cannot be conditionally defined. If a macro
definition occurs inside an <font face="Courier" color=blue>#ifdef</font> block, it will be defined regardless of whether the
<font face="Courier" color=blue>#ifdef</font> evaluates to true or false. The compiler will generate a warning if macro
definitions occur within an <font face="Courier" color=blue>#ifdef</font> block.
<p>
The <font face="Courier" color=blue>#if</font>, <font face="Courier" color=blue>#else</font>, and <font face="Courier" color=blue>#elif</font> directives are also available, but are outside the scope of
this document. Refer to a C reference manual for how to use them.
<p>
<!---->
<a name="Comparison with regular C preprocessors"></a>
<font size=+2><b>Comparison with regular C preprocessors</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
The way in which IC deals with loading multiple files is fundamentally different from the
way in which it is done in standard C. In particular, when using standard C, files are
compiled completely independently of each other, then linked together. In IC, on the
other hand, all files are compiled together. This is why standard C needs function
prototypes and <b>extern</b> global definitions in order for multiple files to share functions
and globals, while IC does not.
<p>
In a standard C preprocessor, preprocessor macros defined in one C file cannot be used in
another C file unless defined again. Also, the scope of macros is only from the point of
definition to the end of the file. The solution then is to have the prototypes, <b>extern</b>
declarations, and macros in header files which are then included at the top of each C file
using the <font face="Courier">#include</font> directive. This style interacts well with the fact that each file is
compiled independent of all the others.
<p>
However, since declarations in IC do not file scope, it would be inconsistent to have a
preprocessor with file scope. Therefore, for consistency it was desirable to give IC
macros the same behavior as globals and functions. Therefore, preprocessor macros have
global scope. If a macro is defined anywhere in the files loaded into IC, it is defined
everywhere. Therefore, the <font face="Courier">#include</font> and
<font face="Courier">#undef</font> directives did not seem to have any
appropriate purpose, and were accordingly left out.
<p>
The fact that <font face="Courier" color=blue>#define</font> directives contained within
<font face="Courier" color=blue>#if</font> blocks are defined regardless of
whether the <font face="Courier" color=blue>#if</font> evaluates to be true or false is a side effect
of making the preprocessor macros have global scope.
<p>
Other than these modifications, the IC preprocessor should be compatible with regular C
preprocessors.
<p>
<!---->
<a name="The IC Library File"></a>
<font size=+3><b>The IC Library File</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
Library files provide standard C functions for interfacing with hardware on the robot
controller board. These functions are written either in C or as assembly language drivers.
Library files provide functions to do things like control motors, make tones, and input
sensors values.
<p>
IC automatically loads the library file every time it is invoked. Depending on which
board is being used, a different library file will be required. IC may be configured to load
different library files as its default; IC will automatically load the correct library for the
board you're using at the moment.
<p>
Separate documentation covers all library functions available for the Handy Board, the Lego RCX, and
the XBC; if you have another board, see your owner's manual for documentation.
<p>
To understand better how the library functions work, study of the library file source code
is recommended; e.g., the main library file for the Handy Board is named <font face="Courier">lib_hb.ic</font>.
<p>
For convenience, a description of some of the more commonly used library functions follows.
<p>
<!---->
<a name="Commonly Used IC Library Functions"></a>
<font size=+2><b>Commonly Used IC Library Functions</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
<pre>
<a name="digitalx"></a>
<font color=darkblue>digital</font>(<port#>);
  <font color=darkgreen>/* <i>returns 0 if the switch attached to the port is open and
     returns 1 if the switch is closed.  Digital ports are numbered
     7-15.  Typically used for bumpers or limit switches.</i> */</font>
<a name="analogx"></a>
<font color=darkblue>analog</font>(<port#>);
  <font color=darkgreen>/* <i>returns the analog value of the port (a value in the range 0-255).
     Analog ports on the handy board are numbered 2-6 and 16-23.  Light
     sensors and range sensors are examples of sensors you would
     use in analog ports (only on Handy Board).</i> */</font>
<font color=darkblue>sleep</font>(&lt;<font face="Times"><i>float_secs</i></font>&gt;);
  <font color=darkgreen>/* <i>waits specified number of seconds</i> */</font>
<a name="tonex"></a>
<font color=darkblue>beep</font>();
  <font color=darkgreen>/* <i>causes a beep sound</i> */</font>
<a name="lightx"></a>
<font color=darkblue>tone</font>(&lt;<font face="Times"><i>float_frequency</i></font>&gt;, &lt;<font face="Times"><i>float_secs</i></font>&gt;)
  <font color=darkgreen>/* <i>plays at specified frequency for specified time (seconds)</i> */</font>
<a name="printfx"></a>
<font color=darkblue>printf</font>(&lt;<font face="Times"><i>string</i></font>&gt;, &lt;<font face="Times"><i>arg1</i></font>&gt;, &lt;<font face="Times"><i>arg2</i></font>&gt;, ... );
  <font color=darkgreen>/* <i>prints &lt;<i>string</i>&gt;.  If the string contains % codes then the &lt;<i>args</i>&gt;
     after the string will be printed in place of the % codes in the
     format specified by the code. %d prints a decimal number. %f
     prints a floating point number. %c prints a character, %b prints
     an integer in binary, %x prints an integer in hexadecimal.</i> */</font>
<a name="motorx"></a>
<font color=darkblue>motor</font>(&lt;<i>motor_#</i>&gt;, &lt;<i>speed</i>&gt;)
  <font color=darkgreen>/* <i>controls the motors. &lt;<i>motor_#</i>&gt; is an integer between 0 and 3 (1
     less for RCX).  &lt;<i>speed</i>&gt; is an integer between -100 and 100 where 0
     means the motor is off and negative numbers run the motor in the
     reverse direction</i> */</font>
<a name="fdx"></a>
<font color=darkblue>fd</font>(&lt;<i>motor_#</i>&gt;);
  <font color=darkgreen>/* <i>turns on the motor specified (direction is determined by plug
     orientation</i> */</font>
<a name="bkx"></a>
<font color=darkblue>bk</font>(&lt;<i>motor_#</i>&gt;);
  <font color=darkgreen>/* <i>turns on the motor specified in the opposite direction from fd</i> */</font>
<a name="offx"></a>
<font color=darkblue>off</font>(&lt;<i>motor_#</i>&gt;);
  <font color=darkgreen>/* <i>turns off the motor specified</i> */</font>
<a name="aox"></a>
<font color=darkblue>ao</font>();
  <font color=darkgreen>/* <i>turns all motor ports off</i> */</font>
</pre>
<!---->
<a name="Processes"></a>
<font size=+2><b>Processes</b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
Processes work in parallel.  Each process, once it is started, will continue until it finishes
or until it is killed by another process using the
<nobr><font face="Courier"><font color=purple>kill_process</font>(&lt;</font><i>process_id</i><font face="Courier">)&gt;);</font></nobr>
statement.  Each process that is active gets 50ms of processing time.  Then the process is
paused temporarily and the next process gets its share of time.  This continues until all
the active process have gotten a slice of time, then it all repeats again.  From the user's
standpoint it appears that all the active processes are running in parallel.
<p>
Processes can communicate with one another by reading and modifying global variables.
The globals can be used as semaphores so that one process can signal another.  Process
IDs may also be stored in globals so that one process can kill another when needed.
<p>
Up to 4 processes initiated by the <nobr><font face="Courier"><font color=purple>start_process</font>()</font></nobr> library function can be active at
any time.
<p>
The library functions for controlling processes are:
<pre><a name="start_processx"></a><font color=darkblue>start_process</font>(&lt;<font face="Times"><i>function_name</i></font>&gt;(&lt;<font face="Times"><i>arg1</i></font>&gt;, &lt;<font face="Times"><i>arg2</i></font>&gt;, . . .));
  <font color=darkgreen>/* <i>start_process returns an integer that is the &lt;process_id&gt;
     and starts the function &lt;function_name&gt; as a separate
     process</i> */</font>
<a name="deferx"></a>
<font color=darkblue>defer</font>();
  <font color=darkgreen>/* <i>when placed in a function that is used as a process this
     will cause that process to give up the remainder of its time
     slice whenever defer is called</i> */</font>
<a name="kill_processx"></a>
<font color=darkblue>kill_process</font>(&lt;<font face="Times"><i>process_id</i></font>&gt;);
  <font color=darkgreen>/* <i>this will terminate the process specified by the
     &lt;process_id&gt;</i> */</font>
</pre>
<!---->
<a name="Encoders"></a> <font size=+2><b>Encoders </b></font> &nbsp;&nbsp;<font size=1><a href="#PM Index">Index</a></font>
<p>
The <font face="Courier"><font color=purple>enable_encoder</font>()</font>
  library function is used to start a process which updates the transition count
  for the encoder specified. The encoder library functions are designed for sensors
  connected to (digital) ports 7,8,12,13 on the Handyboard (The corresponding
  <font face="Courier">&lt;</font><i>encoder#</i><font face="Courier">&gt;</font>
  values are 0,1,2,3), or in 1,2, or 3 on the RCX. Every enabled encoder uses
  a lot of the processor -- so don't enable an encoder unless you are going to
  use it, and <font color=red><i>never put an enable statement inside of a loop</i></font>.
<pre><a name="xenable_encoder"></a><font color=darkblue>enable_encoder</font>(&lt;<font face="Times"><i>encoder#</i></font>&gt;);
  <font color=darkgreen>/* <i>turns on the specified encoder (either 0,1,2, or 3 which are
     plugged into digital ports 7,8, 12 &amp; 13 respectively, on the HB).
     This should be done only once - never enable an already enabled
     encoder.  If an encoder is not enabled, read_encoder will
     always return 0.</i> */</font>
<a name="xdisable_encoder"></a><font color=darkblue>disable_encoder</font>(&lt;<font face="Times"><i>encoder#</i></font>&gt;)
  <font color=darkgreen>/* <i>turns off the specified encoder</i> */</font>
<a name="xreset_encoder"></a><font color=darkblue>reset_encoder</font>(&lt;<font face="Times"><i>encoder#</i></font>&gt;)
  <font color=darkgreen>/* <i>sets the specified encoder value to 0</i> */</font>
<a name="xread_encoder"></a><font color=darkblue>read_encoder</font>(&lt;<font face="Times"><i>encoder#</i></font>&gt;)
  <font color=darkgreen>/* <i>returns an int that is the current value of the specified
     encoder</i> */</font>
</pre>
<p>
<hr>
<!---->
<A NAME="Functions">
<font size=+4><b>Sumo11 Library Function Descriptions</b></font><br>

</center>
<p>
(alphabetic order)
<table cellspacing=5>
<tr><td valign=top><a name="alloff"></a>
	    </td>
    <td><font face="Times"><font face="Courier" color=purple>alloff</font> &nbsp;&nbsp;&nbsp;[Category: Motors] &nbsp;&nbsp;<br>
		<dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>void</font> <font color=purple>alloff</font>()</font><br>
		Turns off all motors. <font face="Courier" color=purple>ao</font> is a short form for
		<font face="Courier" color=purple>alloff</font>.</font></td></tr>

<tr><td valign=top><a name="analog"></a>
        </td>
    <td><font face="Times"><font face="Courier" color=purple>analog</font>  &nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;<br>
		<dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>int</font> <font color=purple>analog</font>(<font color=blue>int</font> p)</font><br>
		Returns value of sensor port numbered p. Result is integer between 0 and 255. If
        the <font face="Courier"><font color=purple>analog</font>()</font> function is applied to a port that is implemented digitally in
        hardware, then the value 255 is returned if the hardware digital reading is 1 (as if a digital switch is open, and the pull up
        resistors are causing a high reading), and the value 0 is returned if the hardware digital reading is 0 (as if a digital switch
        is closed and pulling the reading near ground). Ports are numbered as marked.  Note that on the HB ports 16-22 are floating,
        so without a sensor inserted, the value cannot be predicted.</font></td></tr>

<tr><td valign=top><a name="ao"></a>
		</td>
    <td><font face="Times"><font face="Courier" color=purple>ao</font> &nbsp;&nbsp;&nbsp;[Category: Motors] &nbsp;&nbsp;<br>
		<dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>void</font> <font color=purple>ao</font>()</font><br>
		Turns off all motors.</font></td></tr>

<tr><td valign=top><a name="atan"></a>
		</td>
    <td><font face="Times"><font face="Courier" color=purple>atan</font> &nbsp;&nbsp;&nbsp;[Category: Math] &nbsp;&nbsp;<br>
		<dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>float</font> <font color=purple>atan</font>(<font color=blue>float</font> angle)</font><br>
		Returns the arc tangent of the angle. Angle is specified in radians; the result is in radians.</font></td></tr>

<tr><td valign=top><a name="beep"></a>
		</td>
    <td><font face="Times"><font face="Courier" color=purple>beep</font> &nbsp;&nbsp;&nbsp;[Category: Sound] &nbsp;&nbsp;</a><br>
		<dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>void</font> <font color=purple>beep</font>()</font><br>
		Produces a tone of 500 Hertz for a period of 0.3 seconds. Returns when the tone is finished.</font></td></tr>

<tr><td valign=top><a name="beeper_off"></a>
		</td>
    <td><font face="Times"><font face="Courier" color=purple>beeper_off</font> &nbsp;&nbsp;&nbsp;[Category: Sound] &nbsp;&nbsp;</a><br>
	    <dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>void</font> <font color=purple>beeper_off</font>()</font><br>
		Turns off the beeper.</font></td></tr>

<tr><td valign=top><a name="beeper_on"></a></td>
    <td><font face="Times"><font face="Courier" color=purple>beeper_on</font> &nbsp;&nbsp;&nbsp;[Category: Sound] &nbsp;&nbsp;</a><br>
	    <dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>void</font> <font color=purple>beeper_on</font>()</font><br>
		Turns on the beeper at last frequency selected by the former function. The beeper
        remains on until the <font face="Courier" color=purple>beeper_off</font> function is executed.</font></td></tr>

<tr><td valign=top><a name="bk"></a>
		</td>
    <td><font face="Times"><font face="Courier" color=purple>bk</font> &nbsp;&nbsp;&nbsp;[Category: Motors] &nbsp;&nbsp;</a><br>
		<dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>void</font> <font color=purple>bk</font>(<font color=blue>int</font> m)</font><br>
		Turns motor <font face="Courier">m</font> on in the backward direction.<br>
		Example: <br>
		    <font face="Courier">&nbsp;&nbsp;&nbsp;<font color=purple>bk</font>(1);</font></font></td></tr>

<tr><td valign=top><a name="clear_digital_out"></a>

    <td><font face="Times"><font face="Courier" color=purple>clear_digital_out</font> &nbsp;&nbsp;&nbsp;[Category: DIO] &nbsp;&nbsp;</a><br>
		<dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>int</font> <font color=purple>clear_digital_out</font>(<font color=blue>int</font> channel)</font><br>
        Set expansion board digital output to logic low.</font></td></tr>

<tr><td valign=top><a name="cos"></a>
		</td>
    <td><font face="Times"><font face="Courier" color=purple>cos</font> &nbsp;&nbsp;&nbsp;[Category: Math] &nbsp;&nbsp;</a><br>
		<dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>float</font> <font color=purple>cos</font>(<font color=blue>float</font> angle)</font><br>
		Returns cosine of angle. Angle is specified in radians; result is in radians.</font></td></tr>

<tr><td valign=top><a name="defer"></a>
		</td>
    <td><font face="Times"><font face="Courier" color=purple>defer</font> &nbsp;&nbsp;&nbsp;[Category: Processes] &nbsp;&nbsp;</a><br>
	    <dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>void</font> <font color=purple>defer</font>()</font><br>
		Makes a process swap out immediately after the function is called. Useful if a process knows that it will
		not need to do any work until the next time around the scheduler loop.
		<font face="Courier"><font color=purple>defer</font>()</font> is implemented as a C built-in function.</font></td></tr>

<tr><td valign=top><a name="digital"></a>
		</td>
    <td><font face="Times"><font face="Courier" color=purple>digital</font> &nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;</a><br>
		<dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>int</font> <font color=purple>digital</font>(<font color=blue>int</font> p)</font><br>
		Returns the value of the sensor in sensor port p, as a true/false value (1 for true and 0 for false).
		Sensors are expected to be active low, meaning that they are valued at zero volts in the active, or true,
		state. Thus the library function returns the inverse of the actual reading from the digital hardware:
		if the reading is zero volts or logic zero, the <font face="Courier"><font color=purple>digital</font>()</font>
		function will return true.</font></td></tr>

<tr><td valign=top><a name="disable_encoder"></a>
		</td>
    <td><font face="Times"><font face="Courier" color=purple>disable_encoder</font> &nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;</a><br>
		<dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>void</font> <font color=purple>disable_encoder</font>(<font color=blue>int</font> encoder)</font><br>
		Disables the given encoder and prevents it from counting. Each shaft encoder uses processing time every
		time it receives a pulse while enabled, so they should be disabled when you no longer need the encoder's data.</font></td></tr>

<tr><td valign=top><a name="enable_encoder"></a>
		</td>
    <td><font face="Times"><font face="Courier" color=purple>enable_encoder</font> &nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;</a><br>
		<dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>void</font> <font color=purple>enable_encoder</font>(<font color=blue>int</font> encoder)</font><br>
		Enables the given encoder to start counting pulses and resets its counter to zero.  By default
		encoders start in the disabled state and must be enabled before they start counting.</font></td></tr>

<tr><td valign=top><a name="exp10"></a>
		</td>
    <td><font face="Times"><font face="Courier" color=purple>exp10</font> &nbsp;&nbsp;&nbsp;[Category: Math] &nbsp;&nbsp;</a><br>
		<dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>float</font> <font color=purple>exp10</font>(<font color=blue>float</font> num)</font><br>
		Returns 10 to the num power.</font></td></tr>

<tr><td valign=top><a name="exp"></a>
		</td>
	<td><font face="Times"><font face="Courier" color=purple>exp</font> &nbsp;&nbsp;&nbsp;[Category: Math] &nbsp;&nbsp;</a><br>
		<dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>float</font> <font color=purple>exp</font>(<font color=blue>float</font> num)</font><br>
		Returns e to the num power.</font></td></tr></font></td></tr>

<tr><td valign=top><a name="fd"></a>
		</td>
    <td><font face="Times"><font face="Courier" color=purple>fd</font> &nbsp;&nbsp;&nbsp;[Category: Motors] &nbsp;&nbsp;</a><br>
		<dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>void</font> <font color=purple>fd</font>(<font color=blue>int</font> m)</font><br>
		Turns motor m on in the forward direction.<br>
		Example:<br>
		    <font face="Courier">&nbsp;&nbsp;&nbsp;<font color=purple>fd</font>(3);</font></font></td></tr>

<tr><td valign=top><a name="hog_processor"></a>
		</td>
    <td><font face="Times"><font face="Courier" color=purple>hog_processor</font> &nbsp;&nbsp;&nbsp;[Category: Processes] &nbsp;&nbsp;</a><br>
		<dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>void</font> <font color=purple>hog_processor</font>()</font><br>
		Allocates an additional 256 milliseconds of execution to the currently running process. If this function
		is called repeatedly, the system will wedge and only execute the process that is calling
		<font face="Courier"><font color=purple>hog_processor</font>()</font>.
		Only a system reset will unwedge from this state. Needless to say, this function should be used with
		extreme care, and should not be placed in a loop, unless wedging the machine is the desired outcome.</font></td></tr>

<tr><td valign=top><a name="init_expbd_servos"></a>

    <td><font face="Times"><font face="Courier" color=purple>init_expbd_servos</font> &nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;</a><br>
		<dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>void</font> <font color=purple>init_expbd_servos</font>(<font color=blue>int</font> action)</font><br>
		Enable expansion board servos if <font face="Courier">action=1</font>.
		Disable expansion board servos if <font face="Courier">action=0</font>.</font></td></tr>

<tr><td valign=top><a name="kill_process"></a>
		</td>
    <td><font face="Times"><font face="Courier" color=purple>kill_process</font> &nbsp;&nbsp;&nbsp;[Category: Processes] &nbsp;&nbsp;</a><br>
		<dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>void</font> <font color=purple>kill_process</font>(<font color=blue>int</font> pid);</font><br>
		The <font face="Courier" color=purple>kill_process</font> function is used to destroy processes. Processes are destroyed by passing
		their process ID number to <font face="Courier" color=purple>kill_process</font>.  If the return value is 0, then the process
		was destroyed.  If the return value is 1, then the process was not found.  The following code shows the main process
		creating a <font face="Courier">check_sensor</font> process, and then destroying it one second later:
        <pre>    <font color=blue>void</font> main() {
        <font color=blue>int</font> pid;
        pid=<font color=purple>start_process</font>(check_sensor(2));
        <font color=purple>sleep</font>(1.0);
        <font color=purple>kill_process</font>(pid);
    }</pre></font></td></tr>

<tr><td valign=top><a name="knob"></a>

    <td><font face="Times"><font face="Courier" color=purple>knob</font> &nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;</a><br>
		<dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>int</font> <font color=purple>knob</font>()</font><br>
		Returns a value from 0 to 255 based on the position of a potentiometer. On the 6.270 board,
		the potentiometer is labeled frob knob.</font></td></tr>

<tr><td valign=top><a name="log10"></a>
		</td>
    <td><font face="Times"><font face="Courier" color=purple>log10</font> &nbsp;&nbsp;&nbsp;[Category: Math] &nbsp;&nbsp;</a><br>
		<dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>float</font> <font color=purple>log10</font>(<font color=blue>float</font> num)</font><br>
		Returns the logarithm of <font face="Courier">num</font> to the base 10.</font></td></tr>

<tr><td valign=top><a name="log"></a>
		</td>
    <td><font face="Times"><font face="Courier" color=purple>log</font> &nbsp;&nbsp;&nbsp;[Category: Math] &nbsp;&nbsp;</a><br>
		<dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>float</font> <font color=purple>log</font>(<font color=blue>float</font> num)</font><br>
		Returns the natural logarithm of <font face="Courier">num</font>.</font></td></tr>

<tr><td valign=top><a name="motor"></a>
		</td>
    <td><font face="Times"><font face="Courier" color=purple>motor</font> &nbsp;&nbsp;&nbsp;[Category: Motors] &nbsp;&nbsp;</a><br>
		<dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>void</font> <font color=purple>motor</font>(<font color=blue>int</font> m, <font color=blue>int</font> p)</font><br>
		Turns on motor <font face="Courier">m</font> at power level <font face="Courier">p</font>.
		Power levels range from 100 for full on forward to -100 for full on backward.
		For the RCX, motors A-C are 1-3.</font></td></tr>

<tr><td valign=top><a name="mseconds"></a>
		</td>
    <td><font face="Times"><font face="Courier" color=purple>mseconds</font> &nbsp;&nbsp;&nbsp;[Category: Time] &nbsp;&nbsp;</a><br>
		<dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>long</font> <font color=purple>mseconds</font>()</font><br>
		Returns the count of system time in milliseconds. Time count is reset by hardware reset (i.e., pressing
		reset switch on board) or the function <font face="Courier"><font color=purple>reset_system_time</font>()</font>.
		<br><font face="Courier"><font color=purple>mseconds</font>()</font> is implemented as a C primitive
		(not as a library function).

<tr><td valign=top><a name="msleep"></a>
		</td>
    <td><font face="Times"><font face="Courier" color=purple>msleep</font> &nbsp;&nbsp;&nbsp;[Category: Time] &nbsp;&nbsp;</a><br>
		<dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>void</font> <font color=purple>msleep</font>(<font color=blue>long</font> msec)</font><br>
		Waits for an amount of time equal to or greater than <font face="Courier">msec</font> milliseconds.
		<font face="Courier">msec</font> is a <font face="Courier" color=blue>long</font> integer.<br>
		Example:<br>
		    <font face="Courier">&nbsp;&nbsp;&nbsp;<font color=darkgreen>/* wait for 1.5 seconds */</font><font color=purple> msleep</font>(1500L);</font></font></td></tr>

<tr><td valign=top><a name="off"></a>
		</td>
    <td><font face="Times"><font face="Courier" color=purple>off</font> &nbsp;&nbsp;&nbsp;[Category: Motors] &nbsp;&nbsp;</a><br>
		<dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>void</font> <font color=purple>off</font>(<font color=blue>int</font> m)</font><br>
		Turns off motor <font face="Courier">m</font>. <br>
		Example: <br>
		    <font face="Courier">&nbsp;&nbsp;&nbsp;<font color=purple> off</font>(1);</font></font></td></tr>

<tr><td valign=top><a name="printf"></a>
		</td>
    <td><font face="Times"><font face="Courier" color=purple>printf</font> &nbsp;&nbsp;&nbsp;[Category: Output] &nbsp;&nbsp;</a><br>
		<dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>void</font> <font color=purple>printf</font>(<font color=blue>char</font> s, . . .)</font><br>
    	<p>
    	<b>LCD Screen Printing</b><br>
    	IC has a version of the C function <font face="Courier" color=purple>printf</font> for formatted printing to the LCD screen.
    	The syntax of <font face="Courier" color=purple>printf</font> is the following:<br>
			<font face="Courier">&nbsp;&nbsp;&nbsp;<font color=purple>printf</font>(&lt;<i>format-string </i>&gt;, &lt;<i>arg-1 </i>&gt; , ... , &lt;<i>arg-n </i>&gt; )</font><br>
    	<p>
    	This is best illustrated by some examples.<br>
        <p>
	    <b>Example 1</b>: Printing a message. <br>
	    The following statement prints a text string to the screen:<br>
    		<font face="Courier">&nbsp;&nbsp;&nbsp;<font color=purple>printf</font>(<font color=red>"Hello, world!\n"</font>);</font><br>
		In this example, the format string is simply printed to the screen.  The character
        <font face="Courier">\n</font> at the end of the string signifies end-of-line. When an end-of-line character is
        printed, the LCD screen will be cleared when a subsequent character is printed.
        Thus, most <font face="Courier" color=purple>printf</font> statements are terminated by a <font face="Courier">\n</font>.
        <p>
	    <b>Example 2</b>: Printing a number. <br>
	    The following statement prints the value of the integer
        variable <font face="Courier">x</font> with a brief message:<br>
			<font face="Courier">&nbsp;&nbsp;&nbsp;<font color=purple>printf</font>(<font color=red>"Value is %d\n"</font>, x);</font><br>
			The special form <font face="Courier">%d</font> is used to format the printing of an integer in decimal format.
        <p>
	    <b>Example 3</b>: Printing a number in binary. <br>
	    The following statement prints the value of the
        integer variable <font face="Courier">x</font> as a binary number:<br>
			<font face="Courier">&nbsp;&nbsp;&nbsp;<font color=purple>printf</font>(<font color=red>"Value is %b\n"</font>, x);</font><br>
			The special form <font face="Courier">%b</font> is used to format the printing of an integer in binary
            format. Only the low byte of the number is printed.
        <p>
	    <b>Example 4</b>: Printing a floating point number. <br>
	    The following statement prints the value of
        the floating point variable <font face="Courier">n</font> as a floating point number:<br>
			<font face="Courier">&nbsp;&nbsp;&nbsp;<font color=purple>printf</font>(<font color=red>"Value is %f\n"</font>, n);</font><br>
			The special form <font face="Courier">%f</font> is used to format the printing of floating point number.
        <p>
	    <b>Example 5</b>: Printing two numbers in hexadecimal format:<br>
			<font face="Courier">&nbsp;&nbsp;&nbsp;<font color=purple>printf</font>(<font color=red>"A=%x  B=%x\n"</font>, a, b);</font><br>
		    The form <font face="Courier">%x</font> formats an integer to print in hexadecimal.
        <p>
        <b>Formatting Command Summary</b>
        <table border=1>
        <tr><td align=center>&nbsp;<font face="Times">Format Command</font>&nbsp;</td><td align=center>&nbsp;<font face="Times">Data Type</font>&nbsp;</td><td align=center>&nbsp;<font face="Times">Description</font>&nbsp;</td></tr>
        <tr><td>&nbsp;<font face="Courier">%d</font>&nbsp;</td><td>&nbsp;<font face="Courier" color=blue>int</font>&nbsp;</td><td>&nbsp;<font face="Times">decimal number</font>&nbsp;</td></tr>
        <tr><td>&nbsp;<font face="Courier">%x</font>&nbsp;</td><td>&nbsp;<font face="Courier" color=blue>int</font>&nbsp;</td><td>&nbsp;<font face="Times">hexadecimal number</font>&nbsp;</td></tr>
        <tr><td>&nbsp;<font face="Courier">%b</font>&nbsp;</td><td>&nbsp;<font face="Courier" color=blue>int</font>&nbsp;</td><td>&nbsp;<font face="Times">low byte as binary number</font>&nbsp;</td></tr>
        <tr><td>&nbsp;<font face="Courier">%c</font>&nbsp;</td><td>&nbsp;<font face="Courier" color=blue>int</font>&nbsp;</td><td>&nbsp;<font face="Times">low byte as ASCII character</font>&nbsp;</td></tr>
        <tr><td>&nbsp;<font face="Courier">%f</font>&nbsp;</td><td>&nbsp;<font face="Courier" color=blue>float</font>&nbsp;</td><td>&nbsp;<font face="Times">floating point number</font>&nbsp;</td></tr>
        <tr><td>&nbsp;<font face="Courier">%s</font>&nbsp;</td><td>&nbsp;*<font face="Courier" color=blue>char</font>&nbsp;</td><td>&nbsp;<font face="Times">character array (string)</font>&nbsp;</td></tr>
        </table>
        <p>
        <b>Special Notes</b>:
        The final character position of the LCD screen is used as a system "heartbeat."
        This character continuously blinks between a large and small heart when the
        board is operating properly. If the character stops blinking, the board has failed.
        Characters that would be printed beyond the final character position are
        truncated.
        When using a two-line display, the <font face="Courier"><font color=purple>printf</font>()</font>
        command treats the display as a single longer line (31 characters).
        Printing of <font face="Courier" color=blue>long</font> integers is not presently supported.</font></td></tr>

<tr><td valign=top><a name="random"></a>

    <td><font face="Times"><font face="Courier" color=purple>random</font> &nbsp;&nbsp;&nbsp;[Category: Math] &nbsp;&nbsp;</a><br>
		<dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>int</font> <font color=purple>random</font>(<font color=blue>int</font> m)</font><br>
        "Random" numbers are generated by peeking at system clock; input m is from <font face="Courier">2</font> to 32767.</font></td></tr>
        The return value is in the range <font face="Courier">[0,m-1]</font>.</font></td></tr>

<tr><td valign=top><a name="read_encoder"></a>
		</td>
    <td><font face="Times"><font face="Courier" color=purple>read_encoder</font> &nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;</a><br>
    	<dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>int</font> <font color=purple>read_encoder</font>(<font color=blue>int</font> encoder)</font><br>
		Returns the number of pulses counted by the given encoder since it was enabled or since the last reset,
		whichever was more recent.</font></td></tr>

<tr><td valign=top><a name="reset_encoder"></a>
		</td>
    <td><font face="Times"><font face="Courier" color=purple>reset_encoder</font> &nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;</a><br>
		<dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>void</font> <font color=purple>reset_encoder</font>(<font color=blue>int</font> encoder)</font><br>
		Resets the counter of the given encoder to zero. For an enabled encoder, it is more efficient to reset
		its value than to use <font face="Courier"><font color=purple>enable_encoder</font>()</font> to clear it.</font></td></tr>

<tr><td valign=top><a name="reset_system_time"></a>
		</td>
    <td><font face="Times"><font face="Courier" color=purple>reset_system_time</font> &nbsp;&nbsp;&nbsp;[Category: Time] &nbsp;&nbsp;</a><br>
		<dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>void</font> <font color=purple>reset_system_time</font>()</font><br>
		Resets the system time to zero.</font></td></tr>

<tr><td valign=top><a name="seconds"></a>

    <td><font face="Times"><font face="Courier" color=purple>seconds</font> &nbsp;&nbsp;&nbsp;[Category: Time] &nbsp;&nbsp;</a><br>
		<dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>float</font> <font color=purple>seconds</font>()</font><br>
		Returns the count of system time in seconds, as a floating point number. Resolution is one millisecond.</font></td></tr>

<tr><td valign=top><a name="set_beeper_pitch"></a>
		</td>
    <td><font face="Times"><font face="Courier" color=purple>set_beeper_pitch</font> &nbsp;&nbsp;&nbsp;[Category: Sound] &nbsp;&nbsp;</a><br>
		<dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>void</font> <font color=purple>set_beeper_pitch</font>(<font color=blue>float</font> frequency)</font><br>
		Sets the beeper tone to be <font face="Courier">frequency</font> (measure in Hz). The <font face="Courier" color=purple>beeper_on</font>
		function is then used to turn the beeper on.</font></td></tr>

<tr><td valign=top><a name="set_digital_out"></a>

    <td><font face="Times"><font face="Courier" color=purple>set_digital_out</font> &nbsp;&nbsp;&nbsp;[Category: DIO] &nbsp;&nbsp;</a><br>
        <dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>int</font> <font color=purple>set_digital_out</font>(<font color=blue>int</font>)</font><br>
        Sets the expansion board digital output to logic high.</font></td></tr>

<tr><td valign=top><a name="sin"></a>
		</td>
    <td><font face="Times"><font face="Courier" color=purple>sin</font> &nbsp;&nbsp;&nbsp;[Category: Math] &nbsp;&nbsp;</a><br>
		<dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>float</font> <font color=purple>sin</font>(<font color=blue>float</font> angle)</font><br>
        Returns the sine of <font face="Courier">angle</font>. <font face="Courier">angle</font> is specified in radians;
        result is in radians.</font></td></tr>

<tr><td valign=top><a name="sleep"></a>
		</td>
    <td><font face="Times"><font face="Courier" color=purple>sleep</font> &nbsp;&nbsp;&nbsp;[Category: Time] &nbsp;&nbsp;</a><br>
		<dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>void</font> <font color=purple>sleep</font>(<font color=blue>float</font> sec)</font><br>
		Waits for an amount of time equal to or slightly greater than <font face="Courier">sec</font> seconds.
		<font face="Courier">sec</font> is a floating point number.
		Example:<br>
		    <font face="Courier">&nbsp;&nbsp;&nbsp;<font color=darkgreen>/* wait for 1.5 seconds */</font><font color=purple> sleep</font>(1.5);</font></font></td></tr>

<tr><td valign=top><a name="sonar"></a>

    <td><font face="Times"><font face="Courier" color=purple>sonar</font> &nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;</a><br>
		<dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>int</font> <font color=purple>sonar</font>()</font><br>
        Returns the approximate distance in mm.</font></td></tr>

<tr><td valign=top><a name="sqrt"></a>
		</td>
    <td><font face="Times"><font face="Courier" color=purple>sqrt</font> &nbsp;&nbsp;&nbsp;[Category: Math] &nbsp;&nbsp;</a><br>
		<dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>float</font> <font color=purple>sqrt</font><font color=blue>float</font> num)</font><br>
		Returns the square root of <font face="Courier">num</font>.</font></td></tr>

<tr><td valign=top><a name="start_button"></a>
		</td>
    <td><font face="Times"><font face="Courier" color=purple>start_button</font> &nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;</a><br>
		<dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>int</font> <font color=purple>start_button</font>()</font><br>
		Returns value of button labelled Start (or Escape).<br>
		Example:<br>
		    <font face="Courier">&nbsp;&nbsp;&nbsp;<font color=darkgreen>/* wait for button to be pressed; then wait for it to be<br>
            &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;released so that button press is debounced */</font><br>
            &nbsp;&nbsp;&nbsp;<font color=blue>while</font> (!<font color=purple>start_button</font>()) {}<br>
            &nbsp;&nbsp;&nbsp;<font color=blue>while</font> (<font color=purple>start_button</font>()) {}</font></font></td></tr>

<tr><td valign=top><a name="start_press"></a>

    <td><font face="Times"><font face="Courier" color=purple>start_press</font> &nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;</a><br>
		<dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>void</font> <font color=purple>start_press</font>()</font><br>
		Like <font face="Courier"><font color=purple>stop_press</font>()</font>, but for the Start button.</font></td></tr>

<tr><td valign=top><a name="start_process"></a>
		</td>
    <td><font face="Times"><font face="Courier" color=purple>start_process</font> &nbsp;&nbsp;&nbsp;[Category: Processes] &nbsp;&nbsp;</a><br>
		<dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>int</font> <font color=purple>start_process</font>(&lt;<i><font face="Times">function call</font></i>&gt;);</font><br>
		The <font face="Courier" color=purple>start_process</font> function is used to start a process, which then runs in parallel with other active processes.
		The system keeps track of each running process by assigning a process ID number to it.  <font face="Courier" color=purple>start_process</font> returns the
		process ID number for each process it starts.  The process runs until it finishes or until it is terminated by <font face="Courier" color=purple><a href="#kill_process">kill_process</a></font>.
		Up to 4 processes (in addition to <font face="Courier"><font color=blue>main</font></font>) can by started using <font face="Courier" color=purple>start_process</font>.
		The following code shows the main process
		creating a <font face="Courier">check_sensor</font> process, and then destroying it one second later:
        <pre>    <font color=blue>void</font> main() {
        <font color=blue>int</font> pid;
        pid=<font color=purple>start_process</font>(check_sensor(2));
        <font color=purple>sleep</font>(1.0);
        <font color=purple>kill_process</font>(pid);
    }</pre></font></td></tr>

<tr><td valign=top><a name="stop_button"></a>
		</td>
    <td><font face="Times"><font face="Courier" color=purple>stop_button</font> &nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;</a><br>
		<dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>int</font> <font color=purple>stop_button</font>()</font><br>
		Returns value of button labelled Stop (or Choose): 1 if pressed and 0 if released.
		Example:<br>
		    <font face="Courier">&nbsp;&nbsp;&nbsp;<font color=darkgreen>/* wait until stop button pressed */</font><br>
			&nbsp;&nbsp;&nbsp;<font color=blue>while</font> (!<font color=purple>stop_button</font>()) {}</font></font></td></tr>

<tr><td valign=top><a name="stop_press"></a>

    <td><font face="Times"><font face="Courier" color=purple>stop_press</font> &nbsp;&nbsp;&nbsp;[Category: Sensors] &nbsp;&nbsp;</a><br>
		<dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>void</font> <font color=purple>stop_press</font>()</font><br>
		Waits for the Stop button to be pressed, then released. Then issues a short beep and returns.
		The code for <font face="Courier"><font color=purple>stop_press</font>()</font> is as follows:<br>
			<font face="Courier">&nbsp;&nbsp;&nbsp;<font color=blue>while</font> (!<font color=purple>stop_button</font>());
			<font color=blue>while</font> (<font color=purple>stop_button</font>()); <font color=purple>beep</font>();</font></font></td></tr>

<tr><td valign=top><a name="tan"></a>
		</td>
    <td><font face="Times"><font face="Courier" color=purple>tan</font> &nbsp;&nbsp;&nbsp;[Category: Math] &nbsp;&nbsp;</a><br>
		<dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>float</font> <font color=purple>tan</font>(<font color=blue>float</font> angle)</font><br>
		Returns the tangent of <font face="Courier">angle</font>. <font face="Courier">angle</font> is specified in radians; result is in radians.</font></td></tr>

<tr><td valign=top><a name="test_digital_out"></a>

    <td><font face="Times"><font face="Courier" color=purple>test_digital_out</font> &nbsp;&nbsp;&nbsp;[Category: DIO] &nbsp;&nbsp;</a><br>
        <dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>int</font> <font color=purple>test_digital_out</font>(<font color=blue>int</font> channel)</font><br>
        Returns the last commanded state of the expansion board digital output.</font></td></tr>

<tr><td valign=top><a name="tone"></a>
		</td>
    <td><font face="Times"><font face="Courier" color=purple>tone</font> &nbsp;&nbsp;&nbsp;[Category: Sound] &nbsp;&nbsp;</a><br>
		<dl><dd><font face="Times">Format:<font face="Courier"> <font color=blue>void</font> <font color=purple>tone</font>(<font color=blue>float</font> frequency, <font color=blue>float</font> length)</font><br>
		Produces a tone at pitch <font face="Courier">frequency</font> (measured in Hertz) for length <font face="Courier">seconds</font>. Returns when the tone is finished.
		Both frequency and length are floats.</font></td></tr>
</table>
<A NAME="Simulator"></A>
<H2>Using the IC Simulator</H2><BR>
<BR>
<B>1. Setting up to use the simulator</B>
<BR>
There are 3 requirements that must be fulfilled in order to use the simulator:<BR>
<UL>
<LI>A board that has a valid simulator library must be loaded. If a board does not have a simulator library, a warning will be shown when the user tries to activate the simulator.
<LI>A valid IC file must be loaded
<LI>The IC file must compile with no errors
</UL>
After these conditions are met, the simulator can be activated.<BR>
<BR>
<B>2.Opening the simulator</B>
<BR>
With the IC file you would like to simulate selected in the tab interface, hit the "simulate" button on the top toolbar. This will open the simulator window, with the current IC file loaded and ready to run.<BR>
<BR>
<B>3. Running the simulator</B>
<BR>
To start the simulator running, hit the "Execute" button at the bottom of the simulator window. This will execute whatever code is currently loaded into the simulator. To pause execution, hit the pause button. To resume it, hit the execute button again. To reset the simulator back to its starting state (similar to turning a controller board off and back on), hit the reset button. To exit the simulator and return to the IC compiler window, hit the cancel button.<BR>
<BR>
<B>4. A tour of the simulator window</B>
<BR>
The simulator provides all the inputs and outputs of the controller board it is simulating, including sensors, motors, and any board specific features.<BR>
Sensors are located in the upper left hand box. Sensor type is denoted by the letter next to the sensor number, 'a' standing for analog sensor, 'd' for digital. The values for sensors may be set by either typing in the value in the corresponding box, or using the up and down arrows to change the value. The simulator does not need to be paused in order to change the value, and the program that is currently running will react as soon as any change is made.<BR>
In addition to the usual analog and digital sensors, boards might have certain unique features such as buttons and knobs (i.e. the start/stop buttons on the Handyboard, Prgm/View on the RCX, etc...). These features are available in the box directly below the sensors, and are settable through the same methods as the sensors.<BR>
The right side of the simulator window houses the help and output features.<BR>
In the upper right hand corner is the Show Diagram button. By pressing the board diagram button, the user can bring up a picture of the controller board being simulated, in order to relate port positions to their physical positions on the actual board.<BR>
Below this is the Print Buffer display. This display is used to show what would usually be on the screen of the controller board, and is customized to show the text in the same format as it will be shown on the controller board.<BR>
Finally, the motor output values are displayed below the Print Buffer window. These reflect the PWM settings of the motors available on the board.<BR>
<BR>
<B>5. The simulator interaction and global windows</B>
<BR>
The simulator has an interaction feature, similar to using a real controller board. Users may type commands into the interaction window and it will return the results from the current state of the simulated board. In addition, there is now a global tracking window. This displays the names, types, addresses, and values of globals in the currently loaded program, and updates their values as they change during the course of the program's execution. 
</body>
</html>